linear-issue-worker

Linear Issue Worker

Execute code tasks from Linear issues produced by the linear-issue-creator skill. Read structured sub-issues, resolve dependency order, perform the actual file changes, and keep Linear in sync throughout.

---

Contract with linear-issue-creator

The creator produces a 1 main issue + N sub-issues structure. Each sub-issue contains everything needed for one unit of code work: Task Description, Target Location, Technical Details, Done Criteria, and Dependencies. This skill consumes that structure and turns it into real code changes.

---

Workflow

Step 1 — Receive the Main Issue

The user provides a main issue identifier (e.g., PRI-42).

1. Call Linear:get_issue with includeRelations: true
2. Parse the main issue description to extract:
   • Purpose / Background — why this work exists
   • Goal — desired end state
   • Acceptance Criteria — final validation checklist (used at the very end)
   • Scope — boundaries of the work
   • Impact Area — affected parts of the codebase
3. Keep this context in mind — it guides all sub-issue work, but you do NOT code against the main issue directly

Step 2 — List and Sort Sub-Issues

1. Call Linear:list_issues with parentId set to the main issue identifier
2. For each sub-issue, call Linear:get_issue with includeRelations: true to retrieve blockedBy data
   • If get_issue fails for a sub-issue, retry once. If it still fails, use the data already available from list_issues and check the blocks field of other sub-issues to infer the dependency graph
3. Filter out sub-issues with status Done or Canceled
4. Build a dependency-respecting execution order:
   • A sub-issue is ready when it has no blockedBy entries, or all its blockers are Done
   • Sort ready issues by priority (Urgent first), then creation order
   • If circular dependencies are detected, report to the user and stop

Present the execution plan and wait for user confirmation:

📋 Execution Plan for PRI-42:
1. PRI-43 — [project] Configure hotkey plugin (no dependencies)
2. PRI-44 — [project] Build settings UI (blocked by PRI-43)

Proceed?

Step 3 — Process Each Sub-Issue

For each sub-issue in order, run the full execution cycle below. After completing one sub-issue, re-evaluate the remaining list — previously blocked issues may now be ready.

---

Sub-Issue Execution Cycle

3a. Read and Parse

Parse each section of the sub-issue description:

Section	How to use it
Task Description	Understand what to build / change / fix
Target Location	Open these files to understand current code structure
Technical Details	Plan the implementation — patterns, libraries, API specs
Done Criteria	Exit conditions — every item must be satisfiable
Dependencies	Verify prerequisite sub-issues are already Done

Check the sub-issue's labels to determine approach:

Label	Approach
Front-end	Work in frontend codebase, verify from browser/UI perspective
Back-end	Work in server codebase, verify from API/DB perspective
Feature	Design-first, build the new thing
Bug	Root-cause analysis first, then fix
Refactor	Preserve behavior, improve structure
Chore	Config / build / dependency changes
Perf	Measure before and after
Docs	Documentation changes only

3b. Transition to In Progress + Start Comment

Update the issue status:

Linear:save_issue
  id: "<sub-issue-id>"
  state: "started"

Post a start comment (write in Korean, Professional tone, no AI patterns — natural and direct):

Linear:save_comment
  issueId: "<sub-issue-id>"
  body: |
    ## 🚀 Work Started

    ### Approach
    - [Implementation approach summary — include specific technical decisions]
    - [Key files to modify or create]
    - [Notable decisions or trade-offs]

3c. Perform Code Work

1. Explore — Read files listed in Target Location to understand current state
2. Plan — Based on Technical Details, decide exactly what to change
3. Implement — Create or modify files
4. Verify — Check each Done Criteria item against the changes

Guidelines:

• Respect existing code style and conventions
• If Target Location files don't exist, search nearby directories for the most logical placement and note the deviation in a comment
• If Technical Details reference a library not in the project, check package.json / requirements.txt or equivalent first. Install if reasonable, or note the gap
• Keep changes scoped to what the sub-issue describes — don't refactor unrelated code

3d. Self-Validate Against Done Criteria

Before marking complete, go through each Done Criteria checkbox:

• Confirm the condition is met by the changes
• If a criterion requires runtime verification (e.g., "API returns 422"), explain what was implemented and why it satisfies the criterion

3e. Post Completion Comment

Linear:save_comment
  issueId: "<sub-issue-id>"
  body: |
    ## ✅ Work Complete

    ### Changes
    - `path/to/file1.ts` — [what changed]
    - `path/to/file2.ts` — [new file, what it does]

    ### Done Criteria
    - [x] Criterion 1 — [brief evidence]
    - [x] Criterion 2 — [brief evidence]

    ### Notes
    - [Any deviations, edge cases discovered, etc.]

Comment Quality Guide (Content Skill Principles):

Apply these principles when writing completion comments to improve quality. Target audience: Fullstack developers | Language: Korean | Tone: Professional

1. content-strategy: Structure comments clearly (maintain Changes → Done Criteria → Notes order. Each section delivers the information the reader needs without gaps).
2. content-production: Write specific, verifiable content.
   • "Fixed it" → "Added inventory validation logic to POST /api/orders endpoint, returns 409 when out of stock"
   • "Tests done" → "Added 3 unit tests (normal order, out-of-stock, invalid product ID)"
3. content-humanizer: Remove AI patterns and write in natural Korean.
   • Avoid repeating the same sentence structure — vary verb endings and phrasing
   • Remove unnecessary qualifiers ("effectively," "successfully")
   • Maintain the tone of explaining to a peer developer
4. copy-editing: Focus on Clarity and Specificity.
   • Verify file paths and change descriptions are concrete with no vague expressions
   • Verify Done Criteria evidence is code-level verifiable

3f. Transition to Done

Linear:save_issue
  id: "<sub-issue-id>"
  state: "Done"

3g. Move to Next

Re-evaluate the remaining sub-issues. Issues that were blocked by the just-completed one may now be ready. Pick the next ready sub-issue and repeat from 3a.

---

For exception handling (missing files, unavailable dependencies, ambiguous criteria, blockers, deadlocks), see references/exceptions.md.

Completion

When all sub-issues are processed:

1. Review the main issue's Acceptance Criteria
2. Post a summary comment on the main issue (write in Korean, Professional tone. Apply content skill principles — specific, no AI patterns, clear):

Linear:save_comment
  issueId: "<main-issue-id>"
  body: |
    ## 📋 Overall Completion Report

    ### Completed Sub-Issues
    - [x] SUB-01 — Title
    - [x] SUB-02 — Title

    ### Incomplete Sub-Issues (if any)
    - [ ] SUB-03 — Title (reason: ...)

    ### Acceptance Criteria Review
    - [x] Criterion from main issue — satisfied by SUB-01, SUB-02
    - [ ] Criterion from main issue — not yet met (reason: ...)

    ### Summary
    [Concretely summarize all changes and current state]

3. If all acceptance criteria are met and all sub-issues are Done, inform the user that the work is complete
4. If some criteria are unmet, explain what remains and suggest next steps

---

For Linear API details (state values, description parsing, tool calls, retry policy), see references/linear-api.md.