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):

1. 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):

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