triage

name	triage
description	Moves tracker issues through a structured triage state machine with category and readiness decisions; use to evaluate or prepare work items for implementation.
allowed-tools	Read Grep Glob Bash Write Edit
compatibility	Works with GitHub Issues, Linear, or any issue tracker. Requires setup via setup-matt-pocock-skills to configure label mappings. Pairs with grill-with-docs for issue preparation and to-issues for breaking down work.
metadata	{"tags":"triage, issues, state-machine, project-management, bug-tracking, enhancement","platforms":"Claude, ChatGPT, Gemini, Codex","version":"1.0","source":"mattpocock/skills"}

Triage

Move issues through a structured state machine. Every AI-generated comment must start with:

> *This was generated by AI during triage.*

Roles

Category roles (one per issue):

• bug — something is broken
• enhancement — new feature or improvement

State roles (one per issue):

• needs-triage — needs evaluation
• needs-info — waiting on reporter
• ready-for-agent — fully specified, AFK-implementable
• ready-for-human — needs human (judgment, design, manual testing)
• wontfix — will not be actioned

State transitions: needs-triage → needs-info | ready-for-agent | ready-for-human | wontfix. needs-info returns to needs-triage when reporter replies.

Label strings in the tracker may differ from these canonical names — run /setup-matt-pocock-skills to configure the mapping.

Invocation

Natural language: "Show me what needs attention", "Let's look at #42", "Move #42 to ready-for-agent", "What's ready for agents?"

Show what needs attention

Present three buckets (oldest first):

1. Unlabeled — never triaged
2. needs-triage — evaluation in progress
3. needs-info with reporter activity — needs re-evaluation

Show counts + one-line summary per issue. Let maintainer pick.

Triage a specific issue

1. Gather context — read full issue (body, comments, labels, dates). Check .out-of-scope/ for prior rejections.

2. Recommend — state your category + state recommendation with reasoning. Wait for direction.

3. Reproduce (bugs only) — trace the relevant code, run tests. Report: confirmed repro, failed repro, or insufficient detail.

4. Grill if needed — run a grill-with-docs session to flesh out the issue.

5. Apply outcome:

   • ready-for-agent → post an agent brief
   • ready-for-human → same structure, note why it can't be automated
   • needs-info → post triage notes (template below)
   • wontfix (bug) → polite explanation, close
   • wontfix (enhancement) → write to .out-of-scope/, link comment, close

Quick state override

If maintainer says "move #42 to ready-for-agent" — trust them, apply directly. Confirm changes before acting. Skip grilling. Ask if they want an agent brief.

Needs-info template

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1 (specific and actionable)
- question 2

Resuming a session

If prior triage notes exist, read them, check if reporter answered questions, present updated picture. Don't re-ask resolved questions.

When to use this skill

• Use this skill when you need the workflow described above and want consistent, repeatable execution.

Instructions

1. Identify the task trigger and expected output.
2. Follow the workflow steps in this skill from top to bottom.
3. Validate outputs before moving to the next step.
4. Capture blockers and fallback path if any step fails.

Examples

• Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

Best practices

• Keep outputs deterministic and auditable.
• Prefer small reversible changes over broad risky edits.
• Record assumptions explicitly.

References

• Project standards: .agent-skills/skill-standardization/SKILL.md
• Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh