Linear Issue Reviewer

Linear Issue Reviewer

Review sub-issues completed by linear-issue-worker and decide whether to approve, request changes, or ask for clarification.

Position in Pipeline

| Stage | Skill | Role | |---|---|---| | 1 | linear-issue-creator | Creates main issue + sub-issues with structured templates | | 2 | linear-issue-worker | Picks up sub-issues, performs code work, transitions to Done | | 3 | linear-issue-reviewer | Validates Done sub-issues, approves or rejects |

The creator writes Done Criteria and Acceptance Criteria that serve as the contract for this entire pipeline. The worker fulfills that contract; the reviewer verifies it was fulfilled.

Comment Identifier Convention

Each skill uses a distinct comment prefix so comments can be attributed to the correct stage:

| Skill | Comment Identifiers | |---|---| | linear-issue-worker | ## 🚀 Work Started, ## ✅ Work Complete | | linear-issue-reviewer | ## 리뷰 결과: |

---

Workflow

Step 1 — Receive Main Issue and Collect Sub-Issues

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

1. Call Linear:get_issue with includeRelations: true to fetch the main issue
2. Parse and store the Acceptance Criteria from the main issue description (used in final verification)
3. Call Linear:list_issues with parentId set to the main issue ID
4. For each sub-issue, call Linear:get_issue with includeRelations: true to get full details and comments

Step 2 — Identify Review Targets

Filter sub-issues to find those needing review.

Review target conditions:

• Status is Done
• A ## ✅ Work Complete comment exists (worker's completion report)
• No ## 리뷰 결과: comment exists yet (not reviewed)

Re-review detection:

• If a ## 리뷰 결과: 🔄 Changes Requested comment exists AND a newer ## ✅ Work Complete comment follows it → the worker has re-done the work → this is a re-review target

Status-based handling:

| Sub-Issue Status | Completion Comment | Review Comment | Decision | |---|---|---|---| | Done | Present | Absent | Review target | | Done | Present | Approved | Already reviewed, skip | | In Progress | Present | Changes Requested | Worker fixing, skip | | Done | Present | Changes Requested → then new Work Complete | Re-review target | | Done | Absent | Absent | Exception (see Step 3 exceptions) | | Todo / In Progress | — | — | Skip |

Present the review plan and wait for user confirmation:

Review Targets (PRI-42):
1. PRI-43 — [project] Sub-issue title (first review)
2. PRI-45 — [project] Sub-issue title (re-review)

Skipped:
- PRI-44 — Already Approved
- PRI-46 — Still In Progress

Proceed?

Step 3 — Per Sub-Issue Review Cycle

For each review target, execute the following verification cycle.

---

Sub-Issue Review Cycle

3a. Collect Three Sources

Gather the three sources needed for cross-validation:

| Source | Origin | How to Collect | |---|---|---| | Done Criteria | Creator wrote in sub-issue description | Parse ## Done Criteria section from description | | Completion Comment | Worker's change summary | Find comment containing ## ✅ Work Complete | | Actual Code | Changed files | Extract file paths from the Changes section of completion comment → read files |

Also collect:

• Target Location: Parse ## Target Location section from sub-issue description
• Technical Details: Parse ## Technical Details section from sub-issue description

3b. Verify Done Criteria

Check each Done Criteria item against both the completion comment and actual code:

1. Find evidence in the completion comment for this criterion
2. Verify in actual code that the condition is implemented
3. Cross-validate: does the comment's claim match the code?

| Evidence in Comment | Confirmed in Code | Verdict | |---|---|---| | Yes | Yes | Fulfilled | | Yes | No | Not fulfilled (comment-code mismatch) | | No | Yes | Fulfilled (flag: comment should be updated) | | No | No | Not fulfilled |

3c. Compare Target Location

1. Check the file list specified in the sub-issue's Target Location section
2. Check the file list in the completion comment's Changes section
3. Compare:

• Specified file not changed → flag as possible omission
• Unspecified file changed → flag as possible scope creep
• Reasonable scope extensions (e.g., adding imports, test files) → allow but note

3d. Verify Technical Details Compliance

Cross-check against the Technical Details section:

• Libraries / patterns: Were the specified libraries used? Were the prescribed patterns followed?
• API spec: Do request/response shapes match the spec?
• Logic / data flow: Is the implementation consistent with the described flow?

3e. Code Quality Check

Review for general code quality regardless of what the issue specifies:

• Error handling is appropriate
• No hardcoded values (magic numbers, hardcoded URLs, etc.)
• Follows project conventions and code style
• No leftover debug code (console.log, debugger, commented-out code, etc.)
• Type safety is maintained (if TypeScript)

3f. Determine Verdict

Based on steps 3b–3e, choose one of three verdicts:

| Verdict | Condition | Status Change | |---|---|---| | Approved | All Done Criteria fulfilled, no critical quality issues | Keep Done | | Changes Requested | Any Done Criteria not fulfilled, or critical quality issues found | Done → In Progress ("started") | | Clarification Needed | Implementation choices need explanation, judgment reserved | Keep Done |

3g. Post Review Comment

Write a review comment based on the verdict. Use the templates from references/comment-templates.md.

Review Comment Quality Guide (Content Skill Principles):

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

1. content-strategy: Structure review comments clearly (verdict summary → per-item verification → specific feedback → next steps).
2. content-production: Include specific evidence and code references.

• "There's a problem" → "notifications.service.ts:42 queries notifications without userId validation. Other users' notifications could be exposed."
• "Needs fixing" → "PATCH /notifications/:id/read returns empty body on 404. Should return { error: 'NOT_FOUND', message: '...' } format."

1. content-humanizer: Remove AI patterns and write in the tone of giving feedback to a peer developer.

• "Improvement is needed" → "This part would be better as ~"
• Remove unnecessary formality ("I would like to inform you of the review results")
• Make positive feedback specific too: "Good job" → "The cursor-based pagination implementation is clean"

1. copy-editing: Focus on Clarity, Prove It, and Specificity.

• Verify review findings are not vague
• Verify change requests include specific resolution direction
• Include file paths and line numbers wherever possible

For Changes Requested, also transition the status:

Linear:save_issue
  id: ""
  state: "started"

3h. Move to Next Sub-Issue

Proceed to the next review target and repeat from 3a.

---

Main Issue Final Verification

Execute this only when all sub-issues have been Approved.

Pre-condition Check

1. Confirm every sub-issue has a ## 리뷰 결과: ✅ Approved comment
2. If any sub-issue still has 🔄 Changes Requested or ❓ Clarification Needed as its latest review, do NOT proceed with final verification — inform the user which sub-issues are pending

Acceptance Criteria Cross-Check

1. Retrieve each Acceptance Criteria item from the main issue
2. Map each item to the sub-issue(s) that satisfy it
3. If all items are covered → post final review comment
4. If gaps exist → identify which criteria are unmet and suggest next steps

Post the final review comment on the main issue using the templates from references/comment-templates.md (Final Review sections). Apply the same Review Comment Quality Guide above to the final review comment as well.

---

For exception handling (missing comments, scope creep, conflicts, ambiguous criteria, re-review), see references/exceptions.md.

For Linear API details (state values, description parsing, comment identification, 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.