Triage

Triage

Move issues through a small state machine of triage roles.

Every comment or issue posted during triage must start with:

> *This was generated by AI during triage.*

Assumes your repo has a CONTEXT.md (domain glossary) and docs/adr/ (decisions recorded). If not, run /setup-mateonunez-skills first. Issue tracker and triage label vocabulary come from setup.

Roles

Two category roles:

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

Five state roles:

• needs-triage — you need to evaluate
• needs-info — waiting on reporter for more information
• ready-for-agent — fully specified, ready for an AFK agent
• ready-for-human — needs human implementation
• wontfix — will not be actioned

Every triaged issue carries exactly one category role and one state role. If state roles conflict, flag it and ask before proceeding.

State transitions: unlabeled issue normally goes to needs-triage first. From there it moves to needs-info, ready-for-agent, ready-for-human, or wontfix. needs-info returns to needs-triage once reporter replies. You can override any time — flag unusual transitions and ask before acting.

Invocation

Describe what you want in natural language. I interpret and act. Examples:

• "Show me anything that needs your attention"
• "Let's look at #42"
• "Move #42 to ready-for-agent"
• "What's ready for agents to pick up?"

Show what needs attention

Query the issue 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 — needs re-evaluation

Show counts and one-line summary per issue. Let user pick.

Triage a specific issue

1. Gather context. Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using domain glossary, respecting ADRs in the area. Surface any prior rejection resembling this issue.

1. Recommend. Tell the user your category and state recommendation with reasoning, plus brief codebase summary relevant to the issue. Wait for direction.

1. Reproduce (bugs only). Before grilling, attempt reproduction: read reporter's steps, trace relevant code, run tests or commands. Report what happened — successful repro with code path, failed repro, or insufficient detail (strong needs-info signal). A confirmed repro makes a much stronger agent brief.

1. Grill (if needed). If the issue needs fleshing out, run a grilling session.

1. Apply the outcome:

• ready-for-agent — post an agent brief comment
• ready-for-human — same structure as agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing)
• needs-info — post triage notes (template below)
• wontfix (bug) — polite explanation, then close
• wontfix (enhancement) — write to .out-of-scope/, link from comment, then close
• needs-triage — apply the role. Optional comment if there's partial progress.

Quick state override

If user says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to ready-for-agent without grilling, ask whether they want to write 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
- question 2

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".

Resuming a previous session

If prior triage notes exist on the issue, read them, check whether the reporter answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mateonunez
• Source: mateonunez/skills
• License: MIT

Install and usage instructions live in the source repository linked above.