Quickstart:
npx skills add mattpocock/skills --skill=triage
npx skills update triage
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.
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-spec; to split an existing spec into tickets, use to-tickets. 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-spec, 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.
Join over 70,000 Developers Becoming AI Heroes #
Engineering fundamentals are your biggest advantage. Learn how to leverage them and leave vibe coding behind.
I respect your privacy. Unsubscribe at any time.
Share