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

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

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