/triage-issues

description: Triage open GitHub issues — split into bugs vs features, rank by severity/opportunity, and flag under-specified issues
disable-model-invocation: true
allowed-tools: Bash(gh issue list:*), Bash(gh issue view:*), Bash(gh api:*), Bash(git log:*), Read, Grep, Glob, Agent
argument-hint: "[--label=<filter>] [--milestone=<filter>]"

Issue Triage

You are triaging all open issues on this repository. Your job is to split them into **bugs** and **feature requests**, rank each group, assess how well-specified each issue is, and produce an actionable triage report.

Step 1: Fetch all open issues

Fetch every open issue with metadata:

gh issue list --state open --limit 200 --json number,title,author,labels,assignees,createdAt,updatedAt,body,commentsCount,reactionGroups,milestone

If `$ARGUMENTS` contains `--label=<X>`, append `--label '<X>'` to the command. If it contains `--milestone=<X>`, append `--milestone '<X>'` to the command.

Also fetch recently closed issues (last 14 days) to detect duplicates and already-resolved work:

gh issue list --state closed --search "closed:>=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=14)).strftime("%Y-%m-%d"))')" --limit 100 --json number,title,body,labels,closedAt

**Exclude pull requests** — `gh issue list` may include PRs. Fetch open PR numbers to filter them out:

gh pr list --state open --json number --jq '.[].number'

Remove any issue whose number appears in this list.

Step 2: Classify each issue as Bug or Feature

Read each issue's title, body, and labels to classify it into one of these categories:

Bugs

Issues that describe **broken existing behavior** — something that worked or should work but doesn't. Signals:

• Labels: `bug`, `defect`, `regression`, `crash`, `error`
• Title/body keywords: "broken", "fails", "crash", "panic", "error", "regression", "doesn't work", "unexpected behavior"
• Includes reproduction steps or error output
• References existing functionality not working as documented

Feature Requests

Issues that describe **new or enhanced behavior** — something that doesn't exist yet. Signals:

• Labels: `enhancement`, `feature`, `feature-request`, `improvement`, `proposal`
• Title/body keywords: "add", "support", "implement", "would be nice", "proposal", "RFC", "new"
• Describes a capability the project doesn't have
• Proposes a design or API change

Ambiguous

If an issue doesn't clearly fit either category (e.g., "improve X performance" could be a bug or a feature), classify it as **Ambiguous** and note why.

Step 3: Rate issue detail level

For each issue, assess how well-specified it is on a 3-tier scale:

| Detail Level | Criteria | |-------------|----------| | **Well-specified** | Has clear description of what/why, reproduction steps (bugs) or user story (features), acceptance criteria or expected behavior, and enough context to start working immediately | | **Adequate** | Describes the problem or request clearly, but missing some detail — no repro steps, vague acceptance criteria, or unclear scope. Needs 1-2 clarifying questions before work can start | | **Under-specified** | Vague title-only or single-sentence body, no context on why it matters, no clear definition of done. Needs significant discussion before it's actionable |

Indicators of good specification:

• Code snippets, error logs, or screenshots
• Steps to reproduce (bugs)
• Proposed API/behavior (features)
• Links to related issues or discussions
• Clear "done when" criteria

Step 4: Rank bugs by severity

Score each bug on these dimensions and compute an overall severity rank:

Impact (1-4)

| Score | Level | Description | |-------|-------|-------------| | 4 | **Critical** | Data loss, security vulnerability, complete feature broken, crash in common path | | 3 | **High** | Major feature degraded, workaround exists but painful, affects many users | | 2 | **Medium** | Minor feature broken, easy workaround, affects subset of users | | 1 | **Low** | Cosmetic, edge case, documentation error, minor inconvenience |

Urgency (1-3)

| Score | Level | Description | |-------|-------|-------------| | 3 | **Urgent** | Security issue, regression in recent release, blocking other work | | 2 | **Normal** | Should be fixed in next release cycle | | 1 | **Low** | Fix when convenient, backlog-worthy |

Scope (1-3)

| Score | Level | Description | |-------|-------|-------------| | 3 | **Broad** | Affects core path, multiple modules, or all users | | 2 | **Moderate** | Affects one module or a specific configuration | | 1 | **Narrow** | Affects edge case or single obscure path |

**Bug severity score** = Impact × 2 + Urgency + Scope (base max 14)

Apply a one-time +2 boost if any of the following are true (max 16):

• Has a linked PR already (someone is working on it — fast-track review)
• Is labeled `security`
• Is a regression (worked before, broken now)

Step 5: Rank features by opportunity

Score each feature request on these dimensions:

Value (1-4)

| Score | Level | Description | |-------|-------|-------------| | 4 | **High** | Unlocks new use cases, frequently requested, strategic alignment | | 3 | **Medium-High** | Significant quality-of-life improvement, good user demand signals | | 2 | **Medium** | Nice to have, modest improvement to existing workflow | | 1 | **Low** | Marginal value, niche use case, unclear demand |

Look for value signals in the issue:

• Number of thumbs-up reactions or "+1" comments
• Multiple people asking for the same thing
• Alignment with project roadmap (check CLAUDE.md TODOs)
• Unblocks other features or simplifies architecture

Effort estimate (1-3, inverted — lower effort = higher score)

| Score | Level | Description | |-------|-------|-------------| | 3 | **Small** | <1 day, isolated change, clear implementation path | | 2 | **Medium** | 1-3 days, touches a few modules, some design needed | | 1 | *