Triage Issue

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:

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