Issue Triage

Issue Triage

One-Liner

Work through the issue backlog using a strict state machine — classify, route, and clear with a consistent schema the whole team (and agents) can rely on.

§ 1 · State Machine

Every issue carries one category label and one state label.

Category Labels

State Labels

Rule: An issue must have exactly one category and one state at all times.

§ 2 · Workflow

Step 1 — Queue Overview

At the start of a triage session, pull three buckets:

1. Unlabeled — issues with no category or state label
2. needs-triage — labeled but not yet processed
3. needs-info with recent activity — reporter may have replied

Present counts and summaries. Ask the maintainer which to process first.

Step 2 — Process Each Issue

For each issue:

1. Read the full issue body, linked code, and existing comments
2. Explore the codebase at the relevant location — don't rely on the issue description alone
3. Classify:
   • Assign bug or enhancement
   • If a bug: attempt to reproduce using the described steps; note success/failure
4. Determine state:
   • Missing information → needs-info (write a specific question as a comment)
   • Clear, deterministic, self-contained → ready-for-agent
   • Requires judgment, design decision, or stakeholder input → ready-for-human
   • Out of scope or will not fix → wontfix
5. Confirm your recommendation with the maintainer before applying labels
6. Apply labels and post the appropriate comment

Step 3 — Comment Standards

All comments generated during triage must begin with:

This was generated by AI during triage.

For needs-info comments, write a specific, answerable question. Not "please provide more information" — instead: "What OS and version are you running? What is the exact error message you see?"

For ready-for-agent issues, include an agent brief:

• Exact file(s) to modify
• Behavior to achieve (input/output contract)
• Edge cases to handle
• Tests that should pass

For wontfix enhancements, explain why clearly — future reporters will search and find this answer.

§ 3 · Routing Heuristics

Route to ready-for-agent when:

• The fix is localized to ≤ 3 files
• The expected behavior is unambiguous
• A test can verify the fix deterministically
• No design decision is required

Route to ready-for-human when:

• Multiple valid approaches exist and the trade-off is non-obvious
• The fix requires understanding business context not captured in the codebase
• The issue involves a UI/UX decision
• Security or privacy implications are unclear

Route to needs-info when:

• The reproduction steps are incomplete
• The expected vs actual behavior is unclear
• The environment (OS, version, config) is not specified

§ 4 · State Transition Rules

Valid transitions:

(new) → needs-triage → needs-info ↔ needs-triage
                      → ready-for-agent → (closed: fixed)
                      → ready-for-human → (closed: fixed)
                      → wontfix → (closed)

Flag and confirm with the maintainer before any unusual transition (e.g., re-opening a wontfix).

§ 5 · When to Use This Skill

Use when:

• The issue backlog has accumulated unlabeled or needs-triage issues
• You want to batch-route issues to agents for autonomous fixing
• Onboarding a new contributor — give them ready-for-human issues

Do NOT use when:

• Triaging a single, obviously critical production incident (handle directly)
• The issue tracker has no label support

§ 6 · Relationship to Other Skills