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