triage

Triage

Move issues through the project issue tracker via a small set of triage roles state machine.

If this repo treats external pull requests as a request surface (see issue-tracker configuration), triage also covers them:A PR is an issue with attached code, the same roles, the same states, the same machine, with only the few differences marked "for a PR" below. Per the tracker configuration, parse bare #42 as an issue or PR.

Every comment or issue posted to the issue tracker during triage muststart 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

Two category roles：

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

Five state roles：

• needs-triage: maintainer needs to evaluate
• needs-info: waiting for the reporter to provide more information
• ready-for-agent: fully specified, ready for an AFK agent to pick up
• ready-for-human: requires human implementation
• wontfix: will not be addressed

For a PR, the same states are read against 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 first 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 be provided to you; if not, ask the user to run /setup-matt-pocock-skills。

State transitions: an unlabeled issue usually enters needs-triagefirst; afterwards it moves to needs-info、ready-for-agent、ready-for-human or wontfix。needs-info and returns to needs-triageafter the reporter replies. The maintainer can override at any time; flag transitions that look abnormal and ask before continuing.

Call

The maintainer calls /triage, and describes what they want in natural language. Interpret the request and act. Example:

• "Show me anything that needs my attention"
• "Let's look at #42" (issue or PR)
• "Move #42 to ready-for-agent"
• "What's ready for agents to pick up?"

Show what needs attention

Query the issue tracker and show three buckets, oldest first:

1. Unlabeled: never triaged.
2. needs-triage：evaluation in progress。
3. needs-info with reporter activity since the last triage notes: needs re-evaluation.

When PRs are in scope, include external PRs in these buckets, and annotate each row with [PR] or [issue]. Discovery only surfaces external PRs (the tracker configuration defines who counts as external); PRs actively being worked on by a collaborator are not triage work. This filtering is only for discovery; a PR that is explicitly named will be triaged regardless of author.

Show the count for each bucket, and a one-line summary for each issue. Let the maintainer choose.

Triage a specific issue or PR

1. Gather context. Read the full issue or PR (body, comments, labels, author, dates; for a PR also the diff). Parse any previous triage notes to avoid re-asking about already-resolved questions. Use the project domain glossary to explore the codebase, and follow relevant ADRs. Run two checks against the codebase: (a) redundancy: Search for an existing implementation of the requested behavior by domain concept (not just the wording of the request), and report where you looked. If found, that is an already implemented wontfix（step 5）。(b) prior rejection: Read .out-of-scope/*.md, and surface any prior rejections similar to this request.

2. Recommend. Tell the maintainer your category and state recommendation with reasoning, and give a brief codebase summary relevant to the request (including whether it is already implemented). Wait for instructions.

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

4. Grill (if needed). If the request needs further fleshing out, invoke the Skill tool twice, specifying grilling and domain-modeling, grill it into shape round by round, refining domain terms as decisions settle and updating inline GLOSSARY.md/ADRs。

5. Apply the outcome:

   • ready-for-agent: post an agent brief comment (AGENT-BRIEF.md）。
   • ready-for-human: use the same structure as the agent brief, but explain why it cannot be delegated (judgment calls, external access, design decisions, manual testing).
   • needs-info: post triage notes (see template below).
   • wontfix: close, comment depends onreason：
     • Already implemented: the change already exists in the codebase. Point to where it is;do notwrite to .out-of-scope/(that KB is forrejectedrequests, not for already built).
     • Rejected（bug）: explain politely, then close.
     • Rejected（enhancement）: write to .out-of-scope/, link to it from the comment, then close (OUT-OF-SCOPE.md）。
   • needs-triage: apply role. If there is partial progress, optionally comment.

Quick status override

If the maintainer says "move #42 to ready-for-agent", trust them and directly apply the role. Confirm what you are about to do (role changes, comment, close), then execute. Skip 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

Capture everything already resolved during grilling under "established so far" to avoid losing work. Questions must be specific and actionable, not "please provide more info".

Resume the last session

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