/triage-issue

name: triage-issue
description: "Bug triage: explores codebase for root cause, files GitHub issue with TDD fix plan. Triggers: triage, investigate bug, fix plan, root cause, file issue, bug report."
user-invocable: true
effort: high
argument-hint: "[bug description or symptom]"
agent: debugger
context: fork
allowed-tools: Read, Grep, Glob, Bash, Agent

Triage Issue

$ARGUMENTS

Investigate a bug, find root cause, and create a GitHub issue with a TDD fix plan. Mostly hands-off.

Usage

/triage-issue [bug description or symptom]

What This Command Does

1. **Captures** problem description (ONE question max) 2. **Explores** codebase deeply for root cause 3. **Identifies** fix approach 4. **Designs** TDD fix plan (RED→GREEN cycles) 5. **Creates** GitHub issue via `gh issue create`

Process

1. Capture the Problem

Get brief description. If not provided, ask ONE question: "What's the problem you're seeing?"

Do NOT ask follow-up questions. Start investigating immediately.

2. Explore and Diagnose

Use Agent (subagent_type=Explore) to deeply investigate:

| Target | What to look for | |--------|-----------------| | Manifestation | Where the bug appears (entry points, UI, API) | | Code path | Trace the flow from trigger to symptom | | Root cause | Why it fails (not just the symptom) | | Related code | Similar patterns, adjacent modules, existing tests | | Recent changes | `git log` on relevant files | | Working patterns | Similar code elsewhere that works correctly |

3. Identify Fix Approach

Determine:

• Minimal change to fix root cause
• Affected modules/interfaces
• Behaviors to verify via tests
• Classification: regression, missing feature, or design flaw

4. Design TDD Fix Plan

Ordered list of RED→GREEN cycles. Each cycle is one vertical slice:

• **RED**: Specific test capturing broken/missing behavior
• **GREEN**: Minimal code change to pass that test

Rules:

• Tests verify behavior through public interfaces
• One test at a time, vertical slices
• Tests must survive internal refactors
• Describe behaviors and contracts, not internal structure

5. Create GitHub Issue

Use `gh issue create` with template below. Share URL immediately.

Issue Template

<issue-template>

Problem

• What happens (actual behavior)
• What should happen (expected behavior)
• How to reproduce

Root Cause Analysis

What was found during investigation:

• The code path involved
• Why the current code fails
• Contributing factors

Do NOT include file paths, line numbers, or implementation details. Describe modules, behaviors, and contracts.

TDD Fix Plan

1. **RED**: Write test that [expected behavior] **GREEN**: [Minimal change to pass]

2. **RED**: Write test that [next behavior] **GREEN**: [Minimal change to pass]

**REFACTOR**: [Cleanup after all tests pass]

Acceptance Criteria

• [ ] Criterion 1
• [ ] All new tests pass
• [ ] Existing tests still pass

</issue-template>

Rules

• **MUST** explore the codebase for root cause before filing — symptoms masquerade as causes often
• **MUST** propose a TDD fix plan with ordered RED→GREEN cycles, each a vertical slice
• **NEVER** ask follow-up clarifying questions; one initial question maximum, then investigate autonomously
• **NEVER** include file paths, function names, or line numbers in the issue body — they go stale before the issue is picked up
• **CRITICAL**: the issue must be reproducible. If reproduction steps cannot be determined from the investigation, say so explicitly in the Problem section — do not fabricate them.
• **MANDATORY**: file the issue immediately via `gh issue create` and share the URL — do not ask the user to review a draft first

Gotchas

• `gh issue create` without `--body` opens `$EDITOR`. In automated flows the skill hangs — always pass the body file or inline text.
• "Root cause" often turns out to be two concurrent issues. If the investigation keeps branching, file the most-probable primary cause and note the secondary as a follow-up in the same issue.
• TDD plans with more than ~5 RED→GREEN cycles usually conceal a deeper design issue. Short plans (2-3 cycles) reflect confident root-cause identification; long plans reflect fishing.
• The `debugger` agent explored autonomously but returns a narrative. Parse it for: confirmed hypothesis, code paths, and recent changes. Discard speculation.
• Bugs in framework-adjacent code (middleware, ORM hooks) require test setup that mirrors the framework's call context. A TDD plan that writes the test "like a unit test" may not actually reproduce the framework bug.

When NOT to Use

• For a conversational bug report from a non-engineer — use `/qa-session` first, which returns refined reports this skill can then process
• For a specific reproducible error with known root cause — use `/fix` directly
• For architectural-scale problems — use `/architecture-audit`
• For creating issues from a PRD — use `/prd-to-issues`
• For debugging without filing an issue — use `/debug`