triage-issue

Investigate, find root cause, emit a fix plan shaped as RED-GREEN cycles. Mostly hands-off — minimize user prompts.

Process

1. Capture the problem (one prompt max)

If the user has not already described the bug, ask exactly one question: "What's the problem you're seeing?" Then start investigating. No follow-ups yet.

2. Explore and diagnose

Dispatch an Explore agent. Find:

Where the bug manifests (entry points, UI, API responses)
What code path executes (trace the flow)
Why it fails (root cause, not just symptom)
Related code (similar patterns, adjacent modules, existing tests)

Use git --no-pager grep -n -C 3 <pattern> and ast-grep run -p '<pattern>' -l <lang> -C 3 for structural traces.

3. Identify the fix shape

From the investigation, lock:

Minimal change targeting root cause
Affected modules and their interface contracts
Behaviors needing test coverage
Classification: regression / missing feature / design flaw

4. Design the TDD fix plan

Ordered list of RED-GREEN cycles. Each cycle is a vertical slice through public interfaces.

Rules:

Tests assert on observable behavior through public interfaces, never internal state.
One test at a time. Vertical slicing — never "all tests first, then all code".
Each test must survive radical internal refactors.
Include a final REFACTOR step if cleanup is warranted.
Durability gate: the plan reads like a spec, not a patch. No file paths, no line numbers, no internal struct names.

5. Emit the issue

gh issue create --title "<bug summary>" --body-file <tmp> using the template below. Do NOT ask the user to review first — file it, then share the URL and a one-line root-cause summary.

Template

## Problem
- Actual: what happens
- Expected: what should happen
- Repro: numbered steps (or "non-deterministic; observed in <context>")

## Root Cause Analysis
- Code path involved (described by module + behavior, not file paths)
- Why current code fails (the contract violation, not the line)
- Contributing factors

## TDD Fix Plan
1. **RED:** Write a test asserting <observable behavior>.
   **GREEN:** Minimal change to make it pass.
2. **RED:** Write a test asserting <next observable behavior>.
   **GREEN:** Minimal change to make it pass.
**REFACTOR:** Cleanup after green (extract, rename, deduplicate). Optional.

## Acceptance Criteria
- [ ] Behavior X visible from public interface
- [ ] Behavior Y visible from public interface
- [ ] All new tests pass
- [ ] Existing tests still pass

RED-GREEN Examples Across Stacks

Python (pytest):

RED: test_balance_returns_zero_for_new_account asserts account_service.balance(new_id) == Decimal("0"). GREEN: Initialize default balance in account constructor.

Rust (cargo test):

RED: #[test] fn balance_returns_zero_for_new_account asserts service.balance(id)? == Decimal::ZERO. GREEN: Initialize default balance in Account::new.