Triage Issue

Investigate a reported problem, find its root cause, and create a GitHub issue with a TDD fix plan. This is a mostly hands-off workflow - minimize questions to the user.

Process

1. Capture the problem

Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"

Do NOT ask follow-up questions yet. Start investigating immediately.

2. Explore and diagnose

Use the Agent tool with subagent_type=Explore to deeply investigate the codebase. Your goal is to find:

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

Look at:

• Related source files and their dependencies
• Existing tests (what's tested, what's missing)
• Recent changes to affected files (git log on relevant files)
• Error handling in the code path
• Similar patterns elsewhere in the codebase that work correctly

3. Identify the fix approach

Based on your investigation, determine:

• The minimal change needed 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

Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:

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

Rules:

• Tests verify behavior through public interfaces, not implementation details
• One test at a time, vertical slices (NOT all tests first, then all code)
• Each test should survive internal refactors
• Include a final refactor step if needed
• Durability: Only suggest fixes that would survive radical codebase changes. Describe behaviors and contracts, not internal structure. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state. A good suggestion reads like a spec; a bad one reads like a diff.

5. Create the GitHub issue

Create a GitHub issue using gh issue create with the template below. Do NOT ask the user to review before creating - just create it and share the URL.

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