Create Enriched Issue

Single function that creates a Linear issue with full enrichment: wraps create-issue.sh, applies the validate-issue procedure, adds complexity labels, validates Definition of Ready, and posts a Prep Summary comment. This is NOT a standalone user-facing command — it is a procedure referenced by /new, /go (new findings path), and /approve (sub-issue creation).

Scope: This skill covers issue creation with enrichment. It is NOT about issue validation alone (see validate-issue) or media processing (see process-media).

Inputs

• title (required) — Issue title (monochrome prefix will be applied by validate-issue)
• description (required) — Structured description with Summary, Acceptance Criteria, Scope sections
• type (required) — Issue type: bug, feature, chore, docs, planning, spike
• estimate (optional) — Point estimate. Defaults to M (3 points) if not provided
• extra_labels (optional) — Additional label UUIDs to apply beyond type and complexity
• parent_id (optional) — Parent issue UUID for sub-issue relation

Outputs

After running create-enriched-issue, the caller receives:

• identifier — Linear issue identifier (e.g., ORC-455)
• url — Linear issue URL
• id — Linear issue UUID (needed for relations)

The created issue will have:

• Type label applied
• Estimate set
• Complexity label derived and applied
• Description structure validated
• Monochrome prefix on title
• Assignee and project set (from .linear.json)
• Prep Summary comment posted
• Sub-issue relation (if parent_id provided)

Procedure

E1. Read .linear.json

Read .linear.json from project root. Extract:

• labels.type.* UUIDs
• labels.complexity.* UUIDs
• team.id, assignee.id, projects.* (first value), statuses.backlog

If .linear.json is missing, return error: ".linear.json not found."

E2. Create the issue

bash tools/scripts/create-issue.sh \
  --title "<title>" \
  --description "<description>" \
  --type <type> \
  --estimate <estimate or 3>

Parse the JSON response. Extract data.identifier, data.url, and data.id.

E3. Run validate-issue

Execute the validate-issue skill (V1–V8) against the newly created issue. This ensures:

• Type label is applied
• Estimate is set
• Complexity is derived and applied
• Description structure is valid
• Monochrome prefix is on the title
• Assignee and project are set

E4. Post Prep Summary comment

npx tsx tools/scripts/linear-api.ts create-comment <IDENTIFIER> --body "#### Prep Summary\n\n> **Status:** Ready (9/9 passed)\n>\n> 1. Type label — Passed (<type>)\n> 2. Estimate — Passed (<estimate>pts)\n> 3. Complexity label — Passed (<complexity>)\n> 4. Title convention — Passed\n> 5. Summary section — Passed\n> 6. Acceptance criteria — Passed\n> 7. Scope section — Passed\n> 8. Assignee — Passed\n> 9. Project — Passed"

E5. Link as sub-issue (if parent_id provided)

If parent_id was provided:

npx tsx tools/scripts/linear-api.ts add-relation <CHILD_ID> --type sub-issue --target <PARENT_UUID>

E6. Apply extra labels (if provided)

If extra_labels were provided, fetch current labels and merge:

npx tsx tools/scripts/linear-api.ts update-issue <IDENTIFIER> --labels <ALL_CURRENT_UUIDS>,<EXTRA_LABEL_UUIDS>

E7. Return result

Return to the calling command:

• identifier — e.g., ORC-455
• url — Linear issue URL
• id — Linear issue UUID

Integration points

From /new

/new calls create-enriched-issue in Phase 2 after collecting inputs (title, description, type, estimate). The complexity derivation and DoR validation that were previously inline in /new are now handled by this function.

From /go (new findings)

During Step 5e (Resolve new findings), when a finding warrants a new issue:

create-enriched-issue(
  title: "<finding title>",
  description: "Found during <PARENT_ID>. <finding details>",
  type: "chore",
  estimate: 2
)

This replaces the previous raw create-issue.sh call that skipped enrichment.

From /approve (planning graduation)

When graduating a planning issue into sub-issues, call create-enriched-issue for each sub-issue:

create-enriched-issue(
  title: "<phase heading>",
  description: "Sub-issue of <PARENT_ID>. <phase details>",
  type: <inferred type>,
  estimate: <inferred estimate>,
  parent_id: <parent UUID>
)

Error handling

• If create-issue.sh fails → retry up to 3 times, then return error
• If validate-issue fails (missing assignee/project) → return the issue identifier with a warning
• All other errors are propagated to the caller