skills/docs/engineering/triage.md

Quickstart:

npx skills add mattpocock/skills --skill=triage

npx skills update triage

Source

What it does

triage moves issues on your project's tracker through a small state machine of triage roles — categorise them, verify the claim, grill them into shape if needed, and leave a ready-for-agent brief.

The load-bearing constraint: it never labels blind. Every triaged item carries exactly one category role (bug / enhancement) and one state role (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix), and it recommends and waits — it tells you its category and state call with reasoning, then acts only on your direction. Before anything is promoted to ready-for-agent, it verifies the claim first: a bug gets reproduced, a PR gets checked out and run.

When to reach for it

You invoke this by typing /triage and describing what you want in natural language — the agent won't reach for it on its own. "Show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent".

Reach for it when your issue tracker has raw, unevaluated reports and you want them sorted, verified, and turned into work an agent or human can pick up. To turn a settled conversation into a fresh spec instead, use to-prd; to split an existing PRD into tickets, use to-issues. triage is the reverse direction — it processes what's already landed in the tracker.

Prerequisites

triage reads and writes your issue tracker, so setup-matt-pocock-skills must have configured the tracker and the label mapping first. The role names above are canonical — the actual label strings in your tracker may differ, and that mapping is what setup provides. The config also decides whether external PRs count as a request surface, and who counts as external.

A PR is an issue with attached code

Where the tracker treats external pull requests as a request surface, triage runs them through the same machine: same category roles, same states, same transitions — the states just read against the diff instead of a report. ready-for-agent means a brief is attached and an agent should take the next step on the code; ready-for-human means it's ready to merge. Discovery surfaces only external PRs, but an explicitly named PR is always triaged regardless of author.

Verify before you brief

The step that separates triage from ad-hoc labelling is verification. It reproduces the bug from the reporter's steps, or checks out the PR and runs the tests, and reports back: confirmed with a code path, failed, or insufficient detail (which is itself a strong needs-info signal). It also runs two codebase checks — redundancy (is this already implemented? then it's a wontfix) and prior rejection (does .out-of-scope/ already say no?). A confirmed verification makes a far stronger agent brief; guessing does not.

It's working if

• Every item it touches ends with exactly one category role and one state role — never zero, never two conflicting states.
• It hands you a recommendation with reasoning and waits, rather than relabelling on its own.
• Bugs get reproduced and PRs get run before anything reaches ready-for-agent.
• Every comment it posts to the tracker opens with the > *This was generated by AI during triage.* disclaimer.

Where it fits

triage is the periodic maintenance pass over your issue tracker — run it whenever reports pile up, to keep the queue sorted and the ready-for-agent column trustworthy. It sits at the front of the tracker, upstream of the build chain: the briefs it writes are what tdd later picks up to implement. When a request needs sharpening it leans on grilling and domain-modeling to grill it into shape one question at a time. Its close neighbour is to-prd, which populates the tracker from a fresh conversation where triage processes what's already there. When you're unsure which skill or flow fits, ask-matt routes you.