Purpose
Move issues through a small, explicit state machine instead of ad-hoc judgment calls. Every issue ends triage carrying exactly one category and one state, with the reasoning recorded on the issue itself, so the next person (or agent) starts from the conclusion rather than re-deriving it. Nothing posts to the tracker without the user's approval, and every posted comment begins with a disclosure line: > This comment was generated by AI during triage.
The state machine
Categories: bug (something is broken) and enhancement (new behavior). States:
| State |
Meaning |
Exit criteria |
| needs-triage |
Not yet evaluated |
Evaluation done, moved onward |
| needs-info |
Waiting on the reporter |
Reporter replies, back to needs-triage |
| ready-for-agent |
Fully specified, autonomously implementable |
Carries an agent brief |
| ready-for-human |
Needs human judgment, access, or design |
Brief notes why it cannot be delegated |
| wontfix |
Will not be actioned |
Polite reasoning posted; rejection recorded |
These are canonical names; map them to the team's actual labels by reading the tracker's existing label set first, and ask once when the mapping is ambiguous. An issue carrying conflicting state labels gets flagged to the user before anything else happens.
Workflow
Show what needs attention
When asked broadly ("triage the backlog", "what needs me"), present three buckets, oldest first, with counts and a one-line summary each: unlabeled issues, issues in needs-triage, and needs-info issues where the reporter has replied since the last triage note. Let the user pick; do not start working through the list unprompted.
Triage one issue
- Gather. Read the full issue: body, every comment, labels, reporter, dates, and any prior triage notes so resolved questions are not re-asked. Explore the relevant code area using the project's vocabulary. Check recorded rejections (prior wontfix reasoning, out-of-scope notes in the repo) and surface any that resemble this request; re-litigating a recorded rejection wastes everyone's time.
- Reproduce first, for bugs. Before any questioning, attempt reproduction from the report: trace the code path, run the steps or tests. Report the outcome: reproduced (with the path), not reproduced, or insufficient detail. A confirmed repro is the strongest possible input to the brief; insufficient detail is the strongest possible signal for needs-info. This mirrors the fix skill's iron law: no conclusions about a bug nobody has reproduced.
- Recommend and wait. Category, state, and the reasoning, plus what the code exploration showed. The user directs; quick overrides ("move #42 to ready-for-agent") are followed directly after confirming the actions about to be taken.
- Clarify if needed. When the issue needs fleshing out and the reporter is the user themselves, run interrogate; when the reporter is external, the questions go into a needs-info comment instead.
- Apply the outcome (with approval, see below):
- ready-for-agent: post an agent brief: goal in one sentence, confirmed repro or current behavior, expected behavior, acceptance criteria, constraints and pointers in domain vocabulary (no volatile file paths), and what is explicitly out of scope
- ready-for-human: same brief, plus one line on why it cannot be delegated (judgment call, credentials, design decision, physical testing)
- needs-info: triage-notes comment: "What we have established so far" (so partial work survives) and "What we still need from you", as specific, answerable questions; never "please provide more info"
- wontfix: polite reasoning, then close; for enhancements, record the rejection durably (a note in the repo's docs or AGENTS.md) so future triage finds it
Resuming
When prior triage notes exist, read them, check which outstanding questions the reporter answered, and present the updated picture; re-asking answered questions reads as nobody home.
Guardrails
- Never post comments, apply labels, or close issues without showing the user exactly what will be posted and getting approval; tracker actions are visible to reporters immediately.
- Never close a bug as wontfix without the reasoning posted; silent closes burn reporters.
- The AI-disclosure line leads every posted comment; readers deserve to know.
- One category, one state, always; an issue that fits neither category is a discussion, and triage should say so rather than force it.
Gotchas
- Reproduction before interrogation. Asking the reporter five questions that a ten-minute repro attempt would have answered is the classic triage failure; it costs a round-trip measured in days.
- The established-so-far section is the point of needs-info notes. Without it, the next triage pass starts from zero and the reporter answers the same questions twice.
- ready-for-agent is a high bar. It asserts an agent can complete the work with no human in the loop; when in doubt, ready-for-human with a good brief beats an agent stuck halfway with a vague one.
- Old issues drift. A two-year-old bug report describes a codebase that may no longer exist; verify the report against current code before investing in reproduction.
1---2name: triage-backlog3description: This skill should be used when triaging incoming issues, bug reports, or feature requests on any tracker (GitHub Issues, Jira, Rally, Linear), including evaluating new issues, requesting missing information, marking work ready for implementation, or closing out-of-scope requests. It applies when the user says "triage the backlog", "what needs my attention", "look at issue #42", or "prep these issues for agents". It should not be used for creating work breakdowns from specs (use decompose), for fixing the bug itself (use fix), or for prioritization roadmapping across quarters.4---56## Purpose78Move issues through a small, explicit state machine instead of ad-hoc judgment calls. Every issue ends triage carrying exactly one category and one state, with the reasoning recorded on the issue itself, so the next person (or agent) starts from the conclusion rather than re-deriving it. Nothing posts to the tracker without the user's approval, and every posted comment begins with a disclosure line: `> This comment was generated by AI during triage.`910## The state machine1112Categories: **bug** (something is broken) and **enhancement** (new behavior). States:1314| State | Meaning | Exit criteria |15|---|---|---|16| needs-triage | Not yet evaluated | Evaluation done, moved onward |17| needs-info | Waiting on the reporter | Reporter replies, back to needs-triage |18| ready-for-agent | Fully specified, autonomously implementable | Carries an agent brief |19| ready-for-human | Needs human judgment, access, or design | Brief notes why it cannot be delegated |20| wontfix | Will not be actioned | Polite reasoning posted; rejection recorded |2122These are canonical names; map them to the team's actual labels by reading the tracker's existing label set first, and ask once when the mapping is ambiguous. An issue carrying conflicting state labels gets flagged to the user before anything else happens.2324## Workflow2526### Show what needs attention2728When asked broadly ("triage the backlog", "what needs me"), present three buckets, oldest first, with counts and a one-line summary each: unlabeled issues, issues in needs-triage, and needs-info issues where the reporter has replied since the last triage note. Let the user pick; do not start working through the list unprompted.2930### Triage one issue31321. **Gather.** Read the full issue: body, every comment, labels, reporter, dates, and any prior triage notes so resolved questions are not re-asked. Explore the relevant code area using the project's vocabulary. Check recorded rejections (prior wontfix reasoning, out-of-scope notes in the repo) and surface any that resemble this request; re-litigating a recorded rejection wastes everyone's time.332. **Reproduce first, for bugs.** Before any questioning, attempt reproduction from the report: trace the code path, run the steps or tests. Report the outcome: reproduced (with the path), not reproduced, or insufficient detail. A confirmed repro is the strongest possible input to the brief; insufficient detail is the strongest possible signal for needs-info. This mirrors the fix skill's iron law: no conclusions about a bug nobody has reproduced.343. **Recommend and wait.** Category, state, and the reasoning, plus what the code exploration showed. The user directs; quick overrides ("move #42 to ready-for-agent") are followed directly after confirming the actions about to be taken.354. **Clarify if needed.** When the issue needs fleshing out and the reporter is the user themselves, run interrogate; when the reporter is external, the questions go into a needs-info comment instead.365. **Apply the outcome** (with approval, see below):37 - **ready-for-agent**: post an agent brief: goal in one sentence, confirmed repro or current behavior, expected behavior, acceptance criteria, constraints and pointers in domain vocabulary (no volatile file paths), and what is explicitly out of scope38 - **ready-for-human**: same brief, plus one line on why it cannot be delegated (judgment call, credentials, design decision, physical testing)39 - **needs-info**: triage-notes comment: "What we have established so far" (so partial work survives) and "What we still need from you", as specific, answerable questions; never "please provide more info"40 - **wontfix**: polite reasoning, then close; for enhancements, record the rejection durably (a note in the repo's docs or AGENTS.md) so future triage finds it4142### Resuming4344When prior triage notes exist, read them, check which outstanding questions the reporter answered, and present the updated picture; re-asking answered questions reads as nobody home.4546## Guardrails4748- Never post comments, apply labels, or close issues without showing the user exactly what will be posted and getting approval; tracker actions are visible to reporters immediately.49- Never close a bug as wontfix without the reasoning posted; silent closes burn reporters.50- The AI-disclosure line leads every posted comment; readers deserve to know.51- One category, one state, always; an issue that fits neither category is a discussion, and triage should say so rather than force it.5253## Gotchas5455- **Reproduction before interrogation.** Asking the reporter five questions that a ten-minute repro attempt would have answered is the classic triage failure; it costs a round-trip measured in days.56- **The established-so-far section is the point of needs-info notes.** Without it, the next triage pass starts from zero and the reporter answers the same questions twice.57- **ready-for-agent is a high bar.** It asserts an agent can complete the work with no human in the loop; when in doubt, ready-for-human with a good brief beats an agent stuck halfway with a vague one.58- **Old issues drift.** A two-year-old bug report describes a codebase that may no longer exist; verify the report against current code before investing in reproduction.
brandonburrus