triage-issue

name

triage-issue

description

Triage one Linear issue — action 2 of the five codebase actions — grounded in the Linear database and the single `main` branch. Read the issue from its opening body through every comment, verify a merged PR has not already shipped it, reconcile the ask with the glossary, docs, source, and covering tests at `origin/main`, then comment a test-driven plan naming the minimum implementation and exact blast-radius files. Trigger when the user asks to "triage ENG-NN", "triage this issue", "is this issue still valid", "has this already shipped", or "plan this issue". For the whole portfolio at once use `triage-projects`; to write a new issue or rewrite a wrong one use `author-linear-issue`.

/triage-issue — triage one Linear issue

Before reading or writing in Linear, read docs/public-contributor-safety.md. Use only synthetic examples; never put client data, legal files, real contacts, or production IDs in Linear.

The authoritative procedure is Triage an issue. This skill adds the Linear grounding mechanics; keep durable detail in that doc. Triage ends at the plan comment — implementation is action 3 and starts in its own New Worktree.

1. Read the whole issue

Fetch it with get_issue (pass includeRelations: true) and list_comments, and follow how the request evolved from the opening body through the last comment. Relations matter: a blocking issue or a named duplicate changes the verdict before any code is read.

2. Verify it has not already shipped

The single main branch is the shipped record, and stale-open drift is common — an issue can sit in Backlog with its change already merged. Check before planning, not after:

git fetch origin main

gh pr list -R <owner>/<repo> --state merged \
    --json number,title,headRefName,body,url,mergedAt --limit 100

Derive <owner>/<repo> from the checkout's origin, and repeat for every repository the issue explicitly links. For each candidate PR, call Linear's get_diff with its GitHub url: a linked issue returned there is the canonical association. If no diff resolves, inspect the body for an issue reference; branch names and titles containing ENG-NN are fallback candidates only. Fetch the candidate issue and corroborate it with gitBranchName or another explicit Linear/GitHub link before treating the merge as evidence for this issue. Record when Linear exposes no diff so the verdict does not overclaim a branch-name heuristic.

When no correlated PR matches, grep the merged titles and the relevant source on origin/main for the change itself.

A PR-based check proves no issue shipped the work. It does not prove the thing is absent — a closed vocabulary or a complete-but-unwired module answers to no branch name. When the issue proposes new structure (a frontmatter key, a workflow step, a rule code, a module), also run the source checks in author-linear-issue before calling it valid.

3. Reconcile with the evidence

Read docs/glossary.md, the narrowest doc from docs/index.md, the current source, and the covering tests at origin/main. Reproduce the current behavior where practical using the local KIND loop. When an unknown still blocks a grounded scope, run the smallest throwaway Rust spike and record the command, observation, and conclusion — a spike proves a fact; it is not the implementation.

4. Adjudicate

Every issue lands in exactly one verdict, each with its evidence:

• Still valid — proceed to the plan.
• Already shipped — propose completion, citing the merged PR, its correlation source, and what proves the behavior.
• Duplicate or superseded — name the surviving issue and propose cancellation.
• Blocked on a decision — name the decision, the decider, and the smallest spike that would unblock it.

5. Comment the test-driven plan

For a valid issue, post the plan on the Linear issue with save_comment so a future worktree starts grounded without this conversation:

## Triage plan
**Verdict:** still valid — <one-line grounding>
**Covering tests:** <the test(s) that land with the change>
**Minimum implementation:** <smallest change satisfying the evidence>
**Blast radius:** <exact files a worktree should touch>
**Collisions:** <in-flight lanes touching the same files, or "none">

Name real files and real tests — a plan that says "update the relevant handler" forces the next agent to re-triage.