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

1. 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

1. Filter out sub-issues with status Done or Canceled
2. 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: ""
  state: "started"

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

Linear:save_comment
  issueId: ""
  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: ""
  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)"

1. 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

1. 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: ""
  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: ""
  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]

1. If all acceptance criteria are met and all sub-issues are Done, inform the user that the work is complete
2. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buYoung
• Source: buYoung/skills
• License: MIT

Install and usage instructions live in the source repository linked above.