| 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
- Captures problem description (ONE question max)
- Explores codebase deeply for root cause
- Identifies fix approach
- Designs TDD fix plan (RED→GREEN cycles)
- 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
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
-
RED: Write test that [expected behavior]
GREEN: [Minimal change to pass]
-
RED: Write test that [next behavior]
GREEN: [Minimal change to pass]
REFACTOR: [Cleanup after all tests pass]
Acceptance Criteria
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
