Triage

Triage

Move issues through the project tracker using a small state machine of triage roles.

Every comment or issue posted to the tracker during triage must start with the following disclaimer:

> *This was generated by AI during triage.*

Reference documents

• AGENT-BRIEF.md — how to write durable agent briefs
• OUT-OF-SCOPE.md — how the .out-of-scope/ knowledge base is structured

Roles

Two category roles:

• bug — something is broken
• enhancement — a new feature or improvement

Five state roles:

• needs-triage — maintainer assessment required
• needs-info — waiting on additional information from the reporter
• ready-for-agent — fully specified, ready for an AFK agent
• ready-for-human — requires human implementation
• wontfix — will not be fixed

Each triaged issue must have exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything.

These are the canonical role names — the actual label strings in the tracker may differ. The mapping must be supplied up front — if it is not, run /setup-matt-pocock-skills.

State transitions: an issue with no labels usually lands in needs-triage first; from there it moves to needs-info, ready-for-agent, ready-for-human, or wontfix. From needs-info the issue returns to needs-triage as soon as the reporter replies. The maintainer may override a transition at any time — flag unusual transitions and ask before continuing.

Invocation

The maintainer calls /triage and describes their wish in natural language. Interpret the request and act. Examples:

• "Show me everything that needs my attention"
• "Let's look at #42"
• "Move #42 to ready-for-agent"
• "What's ready for agents?"

Show what needs attention

Query the issue tracker and present three blocks, starting with the oldest:

1. Unlabeled — never triaged.
2. needs-triage — assessment in progress.
3. needs-info with reporter activity after the last triage notes — needs reassessment.

Show the count and a one-line summary per issue. Let the maintainer choose.

Triaging a specific issue

1. Gather context. Read the issue in full (body, comments, labels, reporter, dates). Parse prior triage notes so you do not re-ask questions that have already been answered. Explore the codebase using the project glossary,

2. and respect ADRs in that area. Read .out-of-scope/*.md and surface any prior rejection that resembles this issue.

3. Make a recommendation. Tell the maintainer your category and state recommendation with rationale, plus a short summary of the relevant part of the codebase. Wait for direction.

4. Reproduce (bugs only). Before interrogating anything, attempt to reproduce: read the reporter's steps, trace the relevant code, run tests or commands. Report the outcome — successful reproduction with a code path, failed attempt, or insufficient details (a strong signal to move to needs-info). A confirmed reproduction makes the agent brief much stronger.

5. Interrogate (if needed). If the issue needs to be made concrete, run a /grill-with-docs session.

6. Apply the outcome:

   • ready-for-agent — post a comment with the agent brief (AGENT-BRIEF.md).
   • ready-for-human — same structure as the agent brief, but state why it cannot be delegated (judgment calls, external access, design decisions, manual testing).
   • needs-info — post triage notes (template below).
   • wontfix (bug) — polite explanation, then close.
   • wontfix (enhancement) — record it under .out-of-scope/, link to the file from the comment, then close (OUT-OF-SCOPE.md).
   • needs-triage — set the role. Optionally comment if there has been partial progress.

Quick state override

If the maintainer says "move #42 to ready-for-agent", trust them and set the role directly. Confirm what you are about to do (role changes, comment, close), then act. Skip interrogation. On a transition to ready-for-agent without an interrogation session, ask whether an agent brief should be drafted.

Template for needs-info

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

Capture everything that was clarified during interrogation in the "established so far" section so the work is not lost. Questions must be specific and actionable, not "please provide more information".

Resuming a prior session

If the issue already has triage notes, read them, check whether the reporter has answered the outstanding questions, and present an updated picture before continuing. Do not re-ask about points that have already been settled.