skills/triage/SKILL.md

---
name: triage
description: "Classify, verify, and prepare external bug reports and feature requests into agent-ready briefs. Use when processing incoming issues, validating bug reproductions, rejecting out-of-scope requests, or structuring contributor tickets — even if the user says \"triage these issues\". Do NOT use for internal tickets already produced by to-tickets."
---

# Triage

Classify incoming issues and external pull requests, reproduce bug reports against code, reject out-of-scope requests to `.out-of-scope/`, and synthesize durable, high-context agent briefs.

---

## Core Invariants

1. **Mandatory Disclaimer**: Every comment or issue created during triage must open with `> *This was generated by AI during triage.*`
2. **Category and State Orthogonality**: Every triaged issue must possess exactly one Category (`bug`, `enhancement`) and one State (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`).
3. **Reproduction Before Brief**: Verify bug claims against codebase tests and reproduction steps before promoting to `ready-for-agent`.
4. **Out-of-Scope Knowledge Base**: Rejected enhancement requests must be codified in `.out-of-scope/<slug>.md` with clear rationale to prevent recurring re-triage.
5. **Redundancy Screening**: Search codebase for existing implementations before triaging feature requests; if already implemented, close with an explanation.

---

## Architecture & Map of Content (MOC)

```
[ Incoming Issue / External PR ]
                │
                ▼
┌───────────────────────────────────────┐
│ 1. Redundancy & Out-of-Scope Check    │ ──► Search code & `.out-of-scope/*.md`
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 2. Reproduction & Verification Pass   │ ──► Verify bug or test PR diff locally
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 3. Socratic Grilling & State Decision │ ──► Settle terms, update `CONTEXT.md`
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 4. Outcome Publication                │ ──► Post Agent Brief or Out-of-Scope Record
└───────────────────────────────────────┘
```

| Component | Responsibility | Reference Format |
|---|---|---|
| **Agent Brief** | Self-contained instructions for AFK agents | `skills/triage/AGENT-BRIEF.md` |
| **Out of Scope KB** | Persistent store of rejected proposals | `skills/triage/OUT-OF-SCOPE.md` |
| **Triage State Machine** | Canonical roles and state transitions | `docs/agents/triage-labels.md` |

---

## Step-by-Step Procedure (TWI)

### Step 1: Query Issues Needing Attention
- **Action**: Query tracker for unlabeled issues, `needs-triage` issues, and `needs-info` issues with fresh reporter activity.
- **Key Point**: Include external PRs when configured as a request surface.
- **Why**: Focuses maintainer attention on actionable items requiring triage intervention.

### Step 2: Screen Redundancy & Prior Rejections
- **Action**: Search codebase for existing capabilities and inspect `.out-of-scope/*.md` for prior rejections.
- **Key Point**: If the requested behavior already exists, close as `wontfix` pointing directly to the implementation.
- **Why**: Prevents duplicate feature implementations and wasted engineering cycles.

### Step 3: Reproduce Claim & Formulate Recommendation
- **Action**: Attempt reproduction of bug reports or checkout external PR diffs to run test suites.
- **Key Point**: If reproduction fails due to missing details, move to `needs-info` with specific questions.
- **Inline Checklist**:
  - [ ] Bug reproduction attempted on local environment
  - [ ] Relevant code paths and potential root causes identified
  - [ ] Category and state recommendation presented to maintainer

### Step 4: Apply State & Deliver Agent Brief
- **Action**: Apply maintainer-approved state:
  - `ready-for-agent`: Post structured Agent Brief with reproduction commands and suggested seams.
  - `needs-info`: Post specific question block tagging the reporter.
  - `wontfix` (enhancement): Document in `.out-of-scope/` and close issue.
- **Why**: High-fidelity agent briefs enable downstream autonomous agents to implement fixes without human intervention.

---

## Anti-Rationalization Guardrails

| Tempting Rationalization | Binding Rule | Engineering Rationale |
|---|---|---|
| *"Promote a bug to `ready-for-agent` without reproducing it."* | **Mandatory reproduction pass before agent handover.** | Unverified bug reports send downstream agents on wild goose chases. |
| *"Reject a feature in a short comment without documenting it."* | **Log rejected enhancements in `.out-of-scope/`.** | Undocumented rejections lead to repeatedly re-evaluating the same request. |
| *"Ask the reporter vague questions like 'more details please'."* | **Ask specific, actionable questions in `needs-info`.** | Vague questions delay resolution and frustrate external contributors. |