triage

Triage

Run issues on the project issue tracker through a small state machine made up of triage roles.

If this repository also treats external pull requests (PRs) as request entry points (see the issue-tracker configuration), triage covers them as well:A PR is an issue with code— the same roles, the same states, the same state machine, with only a few differences noted below as "PR-only". Depending on the tracker configuration, resolve bare #42 as an issue or a PR.

Every comment or issue posted to the issue tracker during triage mustbegin with this disclaimer:

> *This was generated by AI during triage.*

Reference documents

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

Roles

Twocategoriesof roles:

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

Fivestatesof roles:

• needs-triage — awaiting maintainer evaluation
• needs-info — awaiting additional information from the reporter
• ready-for-agent — fully specified, ready for an AFK agent to take over
• ready-for-human — requires human implementation
• wontfix — will not be handled

For PRs, the same states correspond to the attached code:ready-for-agent means a brief has been attached and the agent should take the next step on the diff;ready-for-human means it is ready for a human to merge.

Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.

These are the canonical role names — the actual label strings used in the issue tracker may differ. The mapping should already have been provided to you — if not, tell the user to run /setup-matt-pocock-skills。

State transitions: an untagged issue usually enters needs-triagefirst; from there it moves to needs-info、ready-for-agent、ready-for-human or wontfix. After the reporter replies,needs-info returns to needs-triage. The maintainer can override at any time — flag transitions that look unusual, and ask before acting.

Invocation

The maintainer invokes /triage and describes what they want in natural language. Understand the request and act. For example:

• "show me everything that needs my attention"
• "look at #42" (issue or PR)
• "move #42 to ready-for-agent"
• "what can an agent take over?"

Show what needs attention

Query the issue tracker and show three buckets, oldest to newest:

1. Untagged— never triaged.
2. needs-triage— under evaluation.
3. needs-info and the reporter has activity after the last triage note— needs re-evaluation.

When PRs are in scope, put external PRs in these buckets too, and mark each line as [PR] or [issue]. The discovery surface presents onlyexternal PRs (the tracker configuration defines who counts as external) — in-progress PRs by collaborators are not triage work. This filter applies only to the discovery surface; explicitly named PRs must be triaged regardless of author.

Show the count and a one-line summary for each item. Let the maintainer pick.

Triage a specific issue or PR

1. Gather context. Read the full issue or PR (body, comments, labels, author, dates; for a PR also read the diff). Parse previous triage notes and don't re-ask resolved questions. Explore the codebase using the project's domain glossary, and respect the ADRs of relevant areas. Do two checks on the codebase: (a) redundancy— search by domain concept (not just the wording of the request) for whether the requested behavior already exists, and report where you looked. If found, it's already-implemented wontfix(step 5). (b) prior rejection— read .out-of-scope/*.mdand find any entries similar to this request.

2. Give a recommendation. Tell the maintainer your category and status recommendation and reasoning, plus a brief codebase summary relevant to the request — including whether it's already implemented. Wait for instructions.

3. Verify the claim. Before any grilling, first confirm the claim holds up. For a bug, reproduce it following the reporter's steps. For a PR, confirm the diff actually does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code paths), failed, or insufficient detail (a strong needs-info signal). A confirmed verification produces a much stronger agent brief.

4. Grill (if needed). If the request needs more refinement, call the Skill tool twice, passing "grilling" and "domain-modeling" respectively — grill it into shape round by round, and as decisions land, refine the domain terms in sync and update GLOSSARY.md/ADR。

5. Apply the result:

   • ready-for-agent — post the agent brief comment (AGENT-BRIEF.md）。
   • ready-for-human — same structure as the agent brief, but note why it can't be delegated (needs judgment, external access, design decisions, manual testing).
   • needs-info — post a triage note (template below).
   • wontfix — close, and the comment content depends on thereason：
     • already implemented — the change already exists in the codebase. Point out where it is;do notwrite to .out-of-scope/(that knowledge base is forrejectedrequests, not already-implemented ones).
     • rejected (bug) — explain politely, then close.
     • rejected (enhancement) — write to .out-of-scope/, link to it in the comment, then close (OUT-OF-SCOPE.md）。
   • needs-triage — apply that role. If there's partial progress, optionally add a comment.

Quick status override

If the maintainer says "move #42 to ready-for-agent", trust them and apply that role directly. Confirm what you're about to do (role change, comment, close), then act. Skip the grilling. If moving to ready-for-agentwithout a grilling session, ask whether they want an agent brief written.

Needs-info template

## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2

Record everything resolved during the questioning under "established so far" so that work is not lost. Questions must be specific and actionable, not "please provide more information".

Resume the previous session

If there are previous triage notes on the issue or PR, read them, check whether the reporter has answered the unresolved questions, and present the updated picture before continuing. Do not re-ask questions that have already been resolved.