# Triage

> 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`).

- Skill: `spencermarx/triage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add spencermarx/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spencermarx/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: spencermarx (https://skillmd.com/u/spencermarx)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/spencermarx/triage

---


# 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](references/agent-brief.md): how to write durable
  agent briefs.
- [references/rejections.md](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](#quick-state-override)) _is_
that authority, so act on it.

## Show what needs attention

Query the issue tracker and present 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 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

1. **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](references/rejections.md) and surface any match
     to the maintainer instead of re-litigating it.

2. **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.

3. **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.

4. **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.

5. **Apply the outcome:**
   - `ready-for-agent`: post an agent brief comment
     ([references/agent-brief.md](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](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

```markdown
## 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.

