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

| Label | Meaning |
|-------|---------|
| `bug` | Something is broken — actual behavior diverges from intended behavior |
| `enhancement` | Something is missing or could be better — desired behavior does not yet exist |

### State Labels

| Label | Meaning | Who acts next |
|-------|---------|--------------|
| `needs-triage` | Newly opened, not yet reviewed | Triager |
| `needs-info` | More information needed from the reporter | Reporter |
| `ready-for-agent` | Well-specified, deterministic enough for autonomous agent completion | Agent |
| `ready-for-human` | Requires human judgment, creativity, or stakeholder decision | Human engineer |
| `wontfix` | Will not be addressed; rationale documented | — (closed) |

**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

| Skill | When to reach for it |
|-------|---------------------|
| `debug-diagnose` | To reproduce a `bug` during triage |
| `to-prd` | To expand a `ready-for-human` enhancement into a full PRD |
| `zoom-out` | To orient before exploring the codebase for triage context |