Fix Bug

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