Triage Issue

Red Flags

• Issue body names specific file paths or line numbers (stale after any refactor)
• Root cause described as "it just wasn't working" — that's a symptom, not a cause
• TDD fix plan has more than 6 RED/GREEN cycles (not a vertical slice — decompose)
• Fix plan describes internal state changes, not observable behavior changes

Core Process

1. Capture the problem

Get a brief description from the user. If none 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 the Agent tool with subagent_type=Explore to find:

• Where the bug manifests (entry points, UI, API responses)
• What code path is involved (trace the flow)
• Why it fails (root cause, not symptom)
• What related code exists (similar patterns, tests, adjacent modules)

Look at: related source files, existing tests, recent changes (git log on relevant files), error handling in the code path, similar patterns that work correctly.

3. Identify the fix approach

Based on investigation, determine:

• The minimal change to fix the root cause
• Which modules/interfaces are affected
• What behaviors need to be verified via tests
• Whether this is a regression, missing feature, or design flaw

4. Design TDD fix plan

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

• RED: A specific test that captures the broken/missing behavior
• GREEN: The minimal code change to make that test pass

Rules: tests verify behavior through public interfaces, not implementation details. One test at a time. Each test must survive internal refactors.

5. Create the GitHub issue

Use gh issue create. Do NOT ask the user to review before creating — create it and share the URL.

Problem

[What happens (actual) vs what should happen (expected). How to reproduce.]

Root Cause Analysis

[Code path, why it fails, contributing factors — no file paths or line numbers]

TDD Fix Plan

1. RED: Write a test that [describes expected behavior] GREEN: [Minimal change to make it pass]

2. ...

REFACTOR: [Any cleanup needed after all tests pass]

Acceptance Criteria

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

After creating: print the issue URL and a one-line root cause summary.

Verification

• Codebase explored before drawing conclusions
• Root cause identified (cause, not symptom)
• TDD fix plan uses observable behaviors, not implementation details
• Issue body contains no file paths or line numbers
• Each RED/GREEN cycle is a vertical slice
• GitHub issue created and URL returned to user