Triage
Move issues on the project issue tracker through a small state machine of
triage roles.
If this repository treats external pull requests as a request surface (see the
issue tracker configuration), triage covers them too: a PR is an issue with
attached code, with the same roles, states and machine, and a few deltas
marked "for a PR" below. Resolve a bare #42 to an issue or a PR as the tracker
configuration says.
Every comment or issue posted to the issue tracker during triage (rejection and
close comments included) must start with this disclaimer:
> *This was generated by AI during triage.*
Paths below are relative to this skill's directory; resolve them to absolute
paths before running anything.
Where things live
This repository's agent configuration should have been provided to you (the
## Agent skills block pointing at docs/agents/). If it is missing, use the
defaults below and suggest the user run the setup-aclarify-skills skill.
- Issue tracker (
docs/agents/issue-tracker.md): how to list, read,
comment on, label and close issues, and whether PRs are a request surface
(its "PRs as a request surface" line; GitLab calls them MRs). Default: none
configured. With none, triage has nothing to work on: say so, suggest
setup-aclarify-skills, and triage only an issue the user pastes in, posting
nothing.
- Triage labels (
docs/agents/triage-labels.md): the label string for each
state role. Default: the role names themselves (needs-triage, needs-info,
ready-for-agent, ready-for-human, wontfix). Category labels are bug
and enhancement unless that file maps them too. Where the tracker has no
labels (a local markdown tracker), the role goes wherever the tracker file
says, such as a Status: line.
- Glossary and decision records (
docs/agents/domain.md): the domain's
vocabulary and its settled choices. Defaults: GLOSSARY.md at the root (a
multi-context repository adds GLOSSARY-MAP.md), decision records in
docs/adr/. Skip silently what does not exist.
- Out-of-scope folder: where rejected enhancements are recorded. Default:
.out-of-scope/ at the root, unless the repository's agent instructions name
another.
- Checks (
docs/agents/workspace.md, "Checks before commit"): what to run
when verifying a PR. Default: what the agent instructions or CI run.
Reference docs
- references/agent-brief.md: how to write durable
agent briefs.
- references/rejections.md: where rejected requests
are recorded, and the dedup pass against prior rejections.
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 on reporter for more information
ready-for-agent: fully specified, ready for an AFK agent
ready-for-human: needs human implementation
wontfix: will not be actioned
For a PR, the same states read against the attached code: ready-for-agent
means a brief is attached and an 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. One carve-out: wontfix is the terminal no-action state, and its
label marks genuine rejections only. Issues closed because the work is
built, underway or deferred leave the machine with no state label; the close
reason and the closing comment carry the outcome (step 5). That keeps the
wontfix label a precise record of what was ruled out.
These are canonical role names; use the label strings the triage labels file
maps them to, and apply existing labels rather than creating new ones.
State transitions: an unlabeled issue normally goes to needs-triage first;
from there it moves to needs-info, ready-for-agent, ready-for-human, or
wontfix. needs-info returns to needs-triage once the reporter replies. The
maintainer can override at any time; flag transitions that look unusual and ask
before proceeding.
Invocation
A maintainer invokes triage and describes what they want in natural language,
or another agent invokes it while working the tracker. The machine is the same
either way; only who answers the questions changes. Interpret the request and
act. Examples:
- "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?"
Wherever a step says to ask the maintainer and the maintainer is present, ask
them, using your structured-question tool if you have one; otherwise list
numbered options in plain text and stop until they reply.
Running unattended
Triage reads freely, but it writes to a tracker other people read and act on,
so an unattended run carries the work as far as it can and leaves each verdict
with the person it belongs to. Wherever the steps below say to ask the
maintainer, decide which of three applies:
- Ask: a human is present, so ask them.
- Record and proceed: the step is yours. That covers everything read-only
(gathering context, the three checks, verification, investigation), the
reversible working states
needs-triage and needs-info, the category label
(reversible, and already carried in your recommendation), and the
triage-notes comment carrying your reasoning and the alternative you decided
against.
- Pause for the caller: the step is beyond an unattended run's authority.
Post triage notes naming the decision, what you would do, and why; leave the
issue in its working state; stop. A later run resumes from those notes, which
is why the reasoning has to be in them.
Beyond an unattended run's authority, because each either cannot be taken back
or spends someone else's effort on your verdict: closing an issue or PR for
any reason, the wontfix label, writing a rejection record, filing a
new issue, ready-for-agent and ready-for-human (the terminal states
that hand work to a builder), taking an issue back off one of those terminal
states, and writing a durable tracked file, glossary entries and decision
records included. A comment is answerable; a committed file is the repository
speaking. Carry the term or the decision in your triage notes instead. A
maintainer naming the move (Quick state override) is
that authority, so act on it.
Show what needs attention
Query the issue tracker and present three buckets, oldest first:
- Unlabeled: never triaged.
needs-triage: evaluation in progress.
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 tag each line
[PR] or [issue]. Discovery surfaces only external PRs (the tracker
configuration defines who counts as external), so a collaborator's in-flight PR
is not triage work. The filter is discovery-only: an explicitly named PR is
always triaged, whoever wrote it.
Show counts and a one-line summary per item. Let the maintainer pick; an agent
surveying the tracker can stop at the summary.
Triage a specific issue or PR
Gather context. Read the full issue or PR (body, comments, labels,
author, dates; for a PR, the diff too). Parse any prior triage notes so you
don't re-ask resolved questions. Orient in the domain before the code: read
the glossaries so your reasoning and output use the project's vocabulary,
and respect the decision records in the area. Then run three checks, and
report where you looked:
- Redundancy: is the requested behavior already built? Check any specs
the repository keeps of its current capabilities, then search the
codebase by domain concept, not just the request's wording. If found, it
is an "already implemented" closure (step 5).
- In flight: is it already underway? Check open PRs and branches, and any
change proposals the repository keeps. If live work covers the request,
report it; the closure itself happens through step 5's "Already underway"
outcome, after the maintainer's direction.
- Prior rejection: has this been ruled out before? Run the dedup pass in
references/rejections.md and surface any match
to the maintainer instead of re-litigating it.
Recommend. Tell the maintainer your category and state recommendation
with reasoning, plus a brief codebase summary relevant to the request,
including whether it is already implemented, in flight, or previously
rejected. Wait for direction. Unattended, record the recommendation and
carry on into verification; step 5 is the latest an unattended run stops,
and an earlier step pauses if it reaches something beyond your authority.
Verify the claim. Before any grilling, check that the claim holds up.
- For a bug with clear steps, reproduce it from the reporter's steps.
For a bug whose cause is unclear (a flaky behavior, a confusing
regression, "it sometimes 500s"), load the
first-principles-investigation
skill (through your skill tool, /first-principles-investigation, or by
reading its SKILL.md) rather than poking ad hoc: separate what you know from
what you assume, reproduce, and chase the cause until one hypothesis
survives. Without it, reproduce and trace the code path yourself.
- For a PR, confirm the diff does what it claims: check it out and run
the relevant tests and checks.
Report what happened: confirmed (with the code path and cause), refuted, or
blocked on missing detail, which is a strong needs-info signal. A
confirmed verification makes a much stronger agent brief.
Grill (if needed). If the request needs fleshing out, load the
grill-with-docs skill (through your skill tool, /grill-with-docs, or by
reading its SKILL.md) and grill it into shape a round of questions at a time;
it sharpens the domain terms and proposes the decision records worth
writing, each written only on the maintainer's yes. Without it, use
grill-me if installed, or ask the questions yourself one round at a time.
Unattended, grill it yourself: settle what the codebase can settle, record
the reasoning, and treat a decision worth a record or a term worth the
glossary as the maintainer's to own, so pause with the wording you would
have used.
Apply the outcome:
ready-for-agent: post an agent brief comment
(references/agent-brief.md). This is triage's
terminal state and the hand-off point: whoever builds works from the brief.
ready-for-human: same structure as an agent brief, but note why it can't
be delegated (judgment calls, external access, design decisions, manual
testing).
needs-info: post triage notes (template below).
wontfix, the terminal no-action state. The wontfix label is reserved
for genuine rejections; the other closures are told apart by the close
reason (where the tracker has one, such as GitHub's completed and
not planned) and the closing comment. Close according to why:
- Already implemented: point to where it lives (the spec or the code);
close as completed, no
wontfix label, and no rejection record:
that is for rejected requests, not built ones.
- Already underway: point to the PR or change that covers it; close as
completed, no
wontfix label.
- Rejected (bug): polite explanation; close as not planned, with the
wontfix label.
- Rejected (enhancement): record it per
references/rejections.md, link the record
from a comment, then close as not planned, with the
wontfix label.
- Deferred, not rejected: "not now" is roadmap material, not a
rejection. Point at the roadmap entry if the repository keeps one, close
as not planned with no
wontfix label (the comment marks it a
deferral), and suggest a roadmap edit to the maintainer if the direction
is genuinely new.
needs-triage: apply the role. Optional comment if there is partial
progress.
Quick state override
If the maintainer says "move #42 to ready-for-agent", trust them and apply the
role directly. Confirm what you're about to do (role changes, comment, close),
then act. Skip grilling. If moving to ready-for-agent without a grilling
session, ask whether they want an agent brief written.
Unattended, the instruction reaches you from the calling agent, and nothing
distinguishes it from the maintainer's own words, so this section is no way
through the authority line: a caller cannot delegate authority it does not
hold. Act directly only when the move is already yours; when it names one that
pauses, record it in the triage notes, naming who asked, and pause. Relaying the
maintainer's own words is the exception, because then it is the maintainer
deciding.
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 resolved during grilling under "established so far" so the
work isn't lost. Questions must be specific and actionable, not "please provide
more info".
Resuming a previous session
If prior triage notes exist on the issue or PR, read them, check whether the
reporter has answered any outstanding questions, and present an updated picture
before continuing. Don't re-ask resolved questions.
1---2name: triage3description: Move issues, and external pull requests where the repository treats them as requests, through a small state machine of triage roles - categorise, check it is not already built, underway or rejected, verify the claim, grill it into shape, then write the agent-ready brief. Use to triage the tracker, evaluate a named issue or PR, see what needs attention, see what is ready for an agent, or set a triage state. Writes to the issue tracker (labels, comments, closures). Do NOT use to deliberate a hard design fork (`arch-board`), to root-cause a failure outside triage (`first-principles-investigation`), or to chart a multi-session effort (`wayfinder`).4license: MIT5argument-hint: '[what to triage: "what needs attention", #42, "move #42 to ready-for-agent"]'6metadata:7 source: https://skillmd.com/skills/spencermarx/triage8 credits: "Adapted from Matt Pocock's triage skill, https://github.com/mattpocock/skills (MIT)"9---1011# Triage1213Move issues on the project issue tracker through a small state machine of14triage roles.1516If this repository treats external pull requests as a request surface (see the17issue tracker configuration), triage covers them too: **a PR is an issue with18attached code**, with the same roles, states and machine, and a few deltas19marked "for a PR" below. Resolve a bare `#42` to an issue or a PR as the tracker20configuration says.2122Every comment or issue posted to the issue tracker during triage (rejection and23close comments included) **must** start with this disclaimer:2425```26> *This was generated by AI during triage.*27```2829Paths below are relative to this skill's directory; resolve them to absolute30paths before running anything.3132## Where things live3334This repository's agent configuration should have been provided to you (the35`## Agent skills` block pointing at `docs/agents/`). If it is missing, use the36defaults below and suggest the user run the `setup-aclarify-skills` skill.3738- **Issue tracker** (`docs/agents/issue-tracker.md`): how to list, read,39 comment on, label and close issues, and whether PRs are a request surface40 (its "PRs as a request surface" line; GitLab calls them MRs). Default: none41 configured. With none, triage has nothing to work on: say so, suggest42 `setup-aclarify-skills`, and triage only an issue the user pastes in, posting43 nothing.44- **Triage labels** (`docs/agents/triage-labels.md`): the label string for each45 state role. Default: the role names themselves (`needs-triage`, `needs-info`,46 `ready-for-agent`, `ready-for-human`, `wontfix`). Category labels are `bug`47 and `enhancement` unless that file maps them too. Where the tracker has no48 labels (a local markdown tracker), the role goes wherever the tracker file49 says, such as a `Status:` line.50- **Glossary and decision records** (`docs/agents/domain.md`): the domain's51 vocabulary and its settled choices. Defaults: `GLOSSARY.md` at the root (a52 multi-context repository adds `GLOSSARY-MAP.md`), decision records in53 `docs/adr/`. Skip silently what does not exist.54- **Out-of-scope folder**: where rejected enhancements are recorded. Default:55 `.out-of-scope/` at the root, unless the repository's agent instructions name56 another.57- **Checks** (`docs/agents/workspace.md`, "Checks before commit"): what to run58 when verifying a PR. Default: what the agent instructions or CI run.5960## Reference docs6162- [references/agent-brief.md](references/agent-brief.md): how to write durable63 agent briefs.64- [references/rejections.md](references/rejections.md): where rejected requests65 are recorded, and the dedup pass against prior rejections.6667## Roles6869Two **category** roles:7071- `bug`: something is broken72- `enhancement`: new feature or improvement7374Five **state** roles:7576- `needs-triage`: maintainer needs to evaluate77- `needs-info`: waiting on reporter for more information78- `ready-for-agent`: fully specified, ready for an AFK agent79- `ready-for-human`: needs human implementation80- `wontfix`: will not be actioned8182For a PR, the same states read against the attached code: `ready-for-agent`83means a brief is attached and an agent should take the next step on the diff;84`ready-for-human` means it is ready for a human to merge.8586Every triaged issue should carry exactly one category role and one state role.87If state roles conflict, flag it and ask the maintainer before doing anything88else. One carve-out: `wontfix` is the terminal no-action state, and its89**label** marks genuine rejections only. Issues closed because the work is90built, underway or deferred leave the machine with no state label; the close91reason and the closing comment carry the outcome (step 5). That keeps the92`wontfix` label a precise record of what was ruled out.9394These are canonical role names; use the label strings the triage labels file95maps them to, and apply existing labels rather than creating new ones.9697State transitions: an unlabeled issue normally goes to `needs-triage` first;98from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or99`wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The100maintainer can override at any time; flag transitions that look unusual and ask101before proceeding.102103## Invocation104105A maintainer invokes triage and describes what they want in natural language,106or another agent invokes it while working the tracker. The machine is the same107either way; only who answers the questions changes. Interpret the request and108act. Examples:109110- "Show me anything that needs my attention"111- "Let's look at #42" (issue or PR)112- "Move #42 to ready-for-agent"113- "What's ready for agents to pick up?"114115Wherever a step says to ask the maintainer and the maintainer is present, ask116them, using your structured-question tool if you have one; otherwise list117numbered options in plain text and stop until they reply.118119## Running unattended120121Triage reads freely, but it writes to a tracker other people read and act on,122so an unattended run carries the work as far as it can and leaves each verdict123with the person it belongs to. Wherever the steps below say to ask the124maintainer, decide which of three applies:125126- **Ask**: a human is present, so ask them.127- **Record and proceed**: the step is yours. That covers everything read-only128 (gathering context, the three checks, verification, investigation), the129 reversible working states `needs-triage` and `needs-info`, the category label130 (reversible, and already carried in your recommendation), and the131 triage-notes comment carrying your reasoning and the alternative you decided132 against.133- **Pause for the caller**: the step is beyond an unattended run's authority.134 Post triage notes naming the decision, what you would do, and why; leave the135 issue in its working state; stop. A later run resumes from those notes, which136 is why the reasoning has to be in them.137138Beyond an unattended run's authority, because each either cannot be taken back139or spends someone else's effort on your verdict: **closing** an issue or PR for140any reason, the **`wontfix`** label, **writing a rejection record**, **filing a141new issue**, **`ready-for-agent` and `ready-for-human`** (the terminal states142that hand work to a builder), **taking an issue back off one of those terminal143states**, and **writing a durable tracked file**, glossary entries and decision144records included. A comment is answerable; a committed file is the repository145speaking. Carry the term or the decision in your triage notes instead. A146maintainer naming the move ([Quick state override](#quick-state-override)) _is_147that authority, so act on it.148149## Show what needs attention150151Query the issue tracker and present three buckets, oldest first:1521531. **Unlabeled**: never triaged.1542. **`needs-triage`**: evaluation in progress.1553. **`needs-info` with reporter activity since the last triage notes**: needs156 re-evaluation.157158When PRs are in scope, include external PRs in these buckets and tag each line159`[PR]` or `[issue]`. Discovery surfaces only _external_ PRs (the tracker160configuration defines who counts as external), so a collaborator's in-flight PR161is not triage work. The filter is discovery-only: an explicitly named PR is162always triaged, whoever wrote it.163164Show counts and a one-line summary per item. Let the maintainer pick; an agent165surveying the tracker can stop at the summary.166167## Triage a specific issue or PR1681691. **Gather context.** Read the full issue or PR (body, comments, labels,170 author, dates; for a PR, the diff too). Parse any prior triage notes so you171 don't re-ask resolved questions. Orient in the domain before the code: read172 the glossaries so your reasoning and output use the project's vocabulary,173 and respect the decision records in the area. Then run three checks, and174 report where you looked:175 - **Redundancy**: is the requested behavior already built? Check any specs176 the repository keeps of its current capabilities, then search the177 codebase by domain concept, not just the request's wording. If found, it178 is an "already implemented" closure (step 5).179 - **In flight**: is it already underway? Check open PRs and branches, and any180 change proposals the repository keeps. If live work covers the request,181 report it; the closure itself happens through step 5's "Already underway"182 outcome, after the maintainer's direction.183 - **Prior rejection**: has this been ruled out before? Run the dedup pass in184 [references/rejections.md](references/rejections.md) and surface any match185 to the maintainer instead of re-litigating it.1861872. **Recommend.** Tell the maintainer your category and state recommendation188 with reasoning, plus a brief codebase summary relevant to the request,189 including whether it is already implemented, in flight, or previously190 rejected. Wait for direction. Unattended, record the recommendation and191 carry on into verification; step 5 is the latest an unattended run stops,192 and an earlier step pauses if it reaches something beyond your authority.1931943. **Verify the claim.** Before any grilling, check that the claim holds up.195 - For a **bug** with clear steps, reproduce it from the reporter's steps.196 For a bug whose cause is unclear (a flaky behavior, a confusing197 regression, "it sometimes 500s"), load the `first-principles-investigation`198 skill (through your skill tool, `/first-principles-investigation`, or by199 reading its SKILL.md) rather than poking ad hoc: separate what you know from200 what you assume, reproduce, and chase the cause until one hypothesis201 survives. Without it, reproduce and trace the code path yourself.202 - For a **PR**, confirm the diff does what it claims: check it out and run203 the relevant tests and checks.204205 Report what happened: confirmed (with the code path and cause), refuted, or206 blocked on missing detail, which is a strong `needs-info` signal. A207 confirmed verification makes a much stronger agent brief.2082094. **Grill (if needed).** If the request needs fleshing out, load the210 `grill-with-docs` skill (through your skill tool, `/grill-with-docs`, or by211 reading its SKILL.md) and grill it into shape a round of questions at a time;212 it sharpens the domain terms and proposes the decision records worth213 writing, each written only on the maintainer's yes. Without it, use214 `grill-me` if installed, or ask the questions yourself one round at a time.215 Unattended, grill it yourself: settle what the codebase can settle, record216 the reasoning, and treat a decision worth a record or a term worth the217 glossary as the maintainer's to own, so pause with the wording you would218 have used.2192205. **Apply the outcome:**221 - `ready-for-agent`: post an agent brief comment222 ([references/agent-brief.md](references/agent-brief.md)). This is triage's223 terminal state and the hand-off point: whoever builds works from the brief.224 - `ready-for-human`: same structure as an agent brief, but note why it can't225 be delegated (judgment calls, external access, design decisions, manual226 testing).227 - `needs-info`: post triage notes (template below).228 - `wontfix`, the terminal no-action state. The **`wontfix` label is reserved229 for genuine rejections**; the other closures are told apart by the close230 reason (where the tracker has one, such as GitHub's `completed` and231 `not planned`) and the closing comment. Close according to _why_:232 - **Already implemented**: point to where it lives (the spec or the code);233 close as completed, **no** `wontfix` label, and **no** rejection record:234 that is for _rejected_ requests, not built ones.235 - **Already underway**: point to the PR or change that covers it; close as236 completed, **no** `wontfix` label.237 - **Rejected (bug)**: polite explanation; close as not planned, with the238 `wontfix` label.239 - **Rejected (enhancement)**: record it per240 [references/rejections.md](references/rejections.md), link the record241 from a comment, then close as not planned, with the `wontfix` label.242 - **Deferred, not rejected**: "not now" is roadmap material, not a243 rejection. Point at the roadmap entry if the repository keeps one, close244 as not planned with **no** `wontfix` label (the comment marks it a245 deferral), and suggest a roadmap edit to the maintainer if the direction246 is genuinely new.247 - `needs-triage`: apply the role. Optional comment if there is partial248 progress.249250## Quick state override251252If the maintainer says "move #42 to ready-for-agent", trust them and apply the253role directly. Confirm what you're about to do (role changes, comment, close),254then act. Skip grilling. If moving to `ready-for-agent` without a grilling255session, ask whether they want an agent brief written.256257Unattended, the instruction reaches you from the calling agent, and nothing258distinguishes it from the maintainer's own words, so this section is no way259through the authority line: a caller cannot delegate authority it does not260hold. Act directly only when the move is already yours; when it names one that261pauses, record it in the triage notes, naming who asked, and pause. Relaying the262maintainer's own words is the exception, because then it is the maintainer263deciding.264265## Needs-info template266267```markdown268## Triage Notes269270**What we've established so far:**271272- point 1273- point 2274275**What we still need from you (@reporter):**276277- question 1278- question 2279```280281Capture everything resolved during grilling under "established so far" so the282work isn't lost. Questions must be specific and actionable, not "please provide283more info".284285## Resuming a previous session286287If prior triage notes exist on the issue or PR, read them, check whether the288reporter has answered any outstanding questions, and present an updated picture289before continuing. Don't re-ask resolved questions.