Menu
Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce โ minimise โ hypothesise โ instrument โ fix โ regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches โ a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` โ or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs.
Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
| name | triage |
| description | Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. |
Move issues on the project issue tracker through a small state machine of triage roles.
Every comment or issue posted to the issue tracker during triage must start with this disclaimer:
> *This was generated by AI during triage.*
Two category roles:
bug โ something is brokenenhancement โ new feature or improvementFive state roles:
needs-triage โ maintainer needs to evaluateneeds-info โ waiting on reporter for more informationready-for-agent โ fully specified, ready for an AFK agentready-for-human โ needs human implementationwontfix โ will not be actionedEvery triaged issue should carry exactly one category role and one state role.
These are canonical role names โ the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run /setup-matt-pocock-skills if not.
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.
The maintainer invokes /triage and describes what they want in natural language. Examples:
Query the issue tracker and present three buckets, oldest first:
needs-triage โ evaluation in progress.needs-info with reporter activity since the last triage notes โ needs re-evaluation.Gather context. Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions.
Recommend. Tell the maintainer your category and state recommendation with reasoning. Wait for direction.
Reproduce (bugs only). Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands.
Grill (if needed). If the issue needs fleshing out, run a /grill-with-docs session.
Apply the outcome:
ready-for-agent โ post an agent brief comment.ready-for-human โ same structure as an agent brief, but note why it can't be delegated.needs-info โ post triage notes (template below).wontfix (bug) โ polite explanation, then close.wontfix (enhancement) โ write to .out-of-scope/, link to it from a comment, then close.## 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". Questions must be specific and actionable.