# Triage

> Move issues through a state machine with category and state labels — classify as bug or enhancement, assign triage state, reproduce bugs, and track out-of-scope requests. Use when triaging GitHub issues, processing a backlog, or managing issue lifecycle.

- Skill: `manastalukdar/triage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add manastalukdar/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manastalukdar/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: manastalukdar (https://skillmd.com/u/manastalukdar)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/manastalukdar/triage

---


# Triage

Manage issues through a structured state machine. Classify, investigate, and route work to the right place.

Arguments: `$ARGUMENTS` - issue number, issue URL, or blank to triage the oldest `needs-triage` issue

## State Machine

**Categories** (apply one):
- `bug` — unintended behavior, regression, or crash
- `enhancement` — new capability or improvement request

**States** (apply one):
| State | Meaning |
|---|---|
| `needs-triage` | Not yet reviewed — default for new issues |
| `needs-info` | Blocked on more detail from the reporter |
| `ready-for-agent` | Well-specified enough for an AI agent to implement |
| `ready-for-human` | Requires human judgment, architecture decision, or context |
| `wontfix` | Out of scope — will not be addressed |

## Behavior

### 1. Gather Context

```bash
# List open issues needing triage (GitHub CLI)
gh issue list --label "needs-triage" --state open --limit 10 2>/dev/null

# Fetch specific issue if number given
gh issue view "$ARGUMENTS" 2>/dev/null
```

Read the full issue history. Read relevant code before forming an opinion.

### 2. Reproduce (for bugs)

Before classifying as a bug, attempt to reproduce:
- Find the code path described
- Identify whether this is a real regression or expected behavior
- Check if a test already covers this case

```bash
grep -rn "relevant function or error message" . \
  --include="*.ts" --include="*.py" --include="*.js" \
  -l 2>/dev/null | grep -v node_modules | head -10
```

### 3. Recommend Category + State

Output:
```
Issue #42: "Login fails when email has uppercase letters"

Category: bug
Recommended state: ready-for-agent

Reasoning: Reproduced. Email comparison uses strict equality instead of
case-insensitive match. One-line fix in src/auth/validator.ts:47.
No architectural decisions required.
```

For `needs-info`, specify exactly what information is missing:
```
State: needs-info
Missing: steps to reproduce, browser/OS version, whether this is
regression (worked before) or has never worked
```

### 4. Apply Labels + Comment

```bash
# Apply labels via GitHub CLI
gh issue edit "$ISSUE_NUMBER" --add-label "bug,ready-for-agent" \
  --remove-label "needs-triage"

# Add triage comment
gh issue comment "$ISSUE_NUMBER" --body "$(cat <<'EOF'
> *This was generated by AI during triage.*

**Category**: bug
**State**: ready-for-agent

Reproduced: email comparison at `src/auth/validator.ts:47` uses `===` instead of `.toLowerCase()` comparison.

Next step: fix comparison to be case-insensitive. Existing test at `src/auth/validator.test.ts` can be extended with an uppercase email case.
EOF
)"
```

**Every AI-generated comment must begin with the disclaimer:**
```
> *This was generated by AI during triage.*
```

### 5. Out-of-Scope Tracking

When state is `wontfix`, document the rejection:

```bash
mkdir -p .out-of-scope
# Create rejection record
cat > ".out-of-scope/$(date +%Y-%m-%d)-issue-$ISSUE_NUMBER.md" << EOF
# Issue #$ISSUE_NUMBER — [Title]

**Date**: $(date +%Y-%m-%d)
**Request**: [summary of what was asked]
**Reason rejected**: [why it's out of scope]
**Prior requests**: [link any related issues]
EOF
```

This prevents the same request being filed repeatedly and documents the reasoning.

### 6. Bulk Triage Mode

When no argument is given, process `needs-triage` issues oldest-first:

```bash
gh issue list --label "needs-triage" --state open \
  --json number,title,createdAt --jq 'sort_by(.createdAt) | .[0]'
```

Triage one issue, then ask: "Triage next?"

## Examples

```
/triage 42
/triage https://github.com/owner/repo/issues/42
/triage          ← oldest needs-triage issue
```

## Token Optimization

**Expected range**: 400–1,500 tokens (single issue), 200–400 tokens (bulk, per issue)

**Grep-before-Read**: Finds relevant code paths via grep before reading full files for reproduction.

**Early exit**: If issue is already fully labeled (has category + terminal state), reports current state without re-triaging.

**Patterns used**: Grep-before-Read, early exit, Bash for system queries (gh CLI)