---
name: fix-bug
description: "Bug fix workflow — reproduce, diagnose, plan, fix, verify, record. Use when a test fails, a build step fails, or results show an unexpected pattern. Mandates reproduction before diagnosis. Integrates with /validate on exit. NOT for: feature additions, refactors, or while-we're-here cleanups — only the named bug's minimal fix."
---

# Bug Fix Workflow

Structured workflow for diagnosing and fixing a bug.

## Arguments
- `$ARGUMENTS` — bug description or spec name

## Workflow

### Phase 1: Reproduce
- Identify the failing command or test
- Run it and capture the exact error output
- Check `.claude/rules/known-issues.md` — is this a known bug?
- **Build a feedback loop**: before diagnosing, establish a fast, deterministic, repeatable pass/fail signal (failing test, curl script, CLI invocation with fixture input, or headless browser script). If you cannot build a loop after trying multiple approaches, stop and say so — do not proceed to diagnose without one.

### Phase 2: Diagnose
Use subagents to explore the relevant code paths in parallel:
- Trace the error to its root cause
- Identify all files involved in the call chain
- Check if the bug affects other specs/kernels

### Phase 3: Plan
Enter plan mode. Draft the fix:
- Root cause explanation
- Proposed change (minimal and targeted)
- Files to modify
- Risk of regression

Present the plan and **wait for user approval**.

### Phase 4: Fix
- Implement the minimal fix
- Do NOT refactor surrounding code
- Add a test if one doesn't exist for this case

### Phase 5: Verify
- Reproduce the original error — confirm it's fixed
- Run project test suite (e.g., `python3 -m pytest tests/ -v`)
- Check for regressions in related areas

### Phase 6: Record
- Update `.claude/rules/known-issues.md` if this was a known bug (mark as fixed)
- Update CLAUDE.md if new gotchas were discovered