mp-triage

---
name: mp-triage
description: Use when moving issues through a small state machine (bug/enhancement × needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix), prepping briefs that AFK agents can pick up cleanly.
source: https://github.com/mattpocock/skills/blob/main/skills/engineering/triage/SKILL.md
generated: 2026-05-12T18:05:25.940Z
category: concept
audience: engineers
---

## Tutorials

- https://skillmake.xyz/v/mp-triage.mp4

## When to use

- Reviewing the inbox of unlabeled and needs-triage issues for maintainer attention
- Triaging a specific issue (reproduce bug, recommend category and state, post agent brief or triage notes)
- Promoting a fully specified issue to ready-for-agent so an AFK agent can grab it
- Closing an enhancement as wontfix by writing to .out-of-scope/ so the same idea doesn't keep re-surfacing

## Key concepts

### category × state state machine

Every triaged issue carries exactly ONE category role (bug or enhancement) and ONE state role (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). Conflicting state roles get flagged to the maintainer before any action — don't pick one and move on.

### state transitions

Unlabeled → needs-triage → (needs-info | ready-for-agent | ready-for-human | 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.

### AI disclaimer on every comment

Every comment or issue posted during triage MUST start with the disclaimer block: `> *This was generated by AI during triage.*` Non-negotiable — readers need to know what they're looking at.

### three-bucket attention view

When asked 'what needs my attention', query the tracker and present three buckets, oldest first: 1) Unlabeled — never triaged. 2) needs-triage — evaluation in progress. 3) needs-info with reporter activity since last triage notes. Show counts and a one-line summary; let the maintainer pick.

### reproduce bugs before grilling

For bug-category issues, attempt reproduction BEFORE any grilling — read the reporter's steps, trace the code, run tests or commands. Report what happened: successful repro with code path, failed repro, or insufficient detail (a strong needs-info signal). A confirmed repro makes a much stronger agent brief.

### .out-of-scope/ knowledge base

When closing an enhancement as wontfix, write the reason to .out-of-scope/<slug>.md, link to it from a closing comment, then close. Future triage reads .out-of-scope/*.md to surface prior rejections that resemble new issues — prevents the same idea from being re-litigated every quarter.

### agent brief vs ready-for-human

ready-for-agent gets an AGENT-BRIEF-formatted comment so an AFK agent can pick it up cleanly. ready-for-human uses the same structure but notes WHY it can't be delegated — judgment calls, external access, design decisions, manual testing. Same shape, different audience.

## API reference

```
Mandatory AI disclaimer (every comment)
```

Prepended to every triage-generated comment or issue body. The labels and role mappings are project-specific; this disclaimer is not.

```
> *This was generated by AI during triage.*
```

```
Triage-a-specific-issue procedure
```

The numbered loop for working a single issue. Steps 3 and 4 are bugs-only and grilling-only respectively.

```
1. Gather context — full issue, comments, labels, reporter, dates, prior triage notes. Explore the codebase using CONTEXT.md. Read .out-of-scope/*.md for prior rejections.
2. Recommend — tell the maintainer your category + state recommendation with reasoning, plus a brief codebase summary. Wait for direction.
3. Reproduce (bugs only) — attempt before any grilling.
4. Grill (if needed) — run a /grill-with-docs session to flesh it out.
5. Apply the outcome:
   - ready-for-agent → post an AGENT-BRIEF comment
   - ready-for-human → same brief, with reason it can't be delegated
   - needs-info → post the triage-notes template
   - wontfix (bug) → polite explanation, then close
   - wontfix (enhancement) → write to .out-of-scope/, link from a comment, then close
   - needs-triage → apply the role; optional comment if there's partial progress
```

```
needs-info template
```

Post this format on a needs-info issue. 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'.

```
## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2
```

```
Quick state override
```

When the maintainer says 'move #42 to ready-for-agent', trust them. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling.

```
Maintainer: "Move #42 to ready-for-agent."

You: "Confirming: I'll add the ready-for-agent label and remove needs-triage. Do you want me to write an agent brief, or is the issue body self-sufficient?"

(then apply on confirmation)
```

## Gotchas

- Every triage comment MUST start with `> *This was generated by AI during triage.*` — non-negotiable.
- Exactly one category role AND one state role per issue. Conflicting state roles must be flagged to the maintainer before any action.
- Reproduce bugs BEFORE grilling. A confirmed repro changes the recommendation and the brief.
- Read .out-of-scope/*.md during context gathering — surface prior rejections that resemble the new issue.
- When moving to wontfix on an enhancement, WRITE the reason to .out-of-scope/<slug>.md — the knowledge base is how repeat ideas stop costing time.
- Resuming a previous session: read prior triage notes, check whether the reporter has answered, and present an updated picture before continuing. Don't re-ask resolved questions.
- Role label strings are project-specific — the canonical names in this skill (bug/enhancement, needs-triage, etc.) may map to different label strings in the tracker. The mapping is provided by /setup-matt-pocock-skills.
- Flag unusual state transitions (e.g. skipping needs-triage) and ask before proceeding. The maintainer can override, but should do so explicitly.

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/engineering/triage/SKILL.md on 2026-05-12T18:05:25.940Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-triage/SKILL.md