debugging-protocollisted

# Debugging Protocol A systematic workflow for investigating and fixing bugs. The core discipline: **evidence before hypotheses, hypotheses before fixes, one variable at a time.** Most debugging time is wasted by skipping straight to fixes based on pattern-matching — this protocol exists to prevent that. ## Phase 0: Reproduce Never debug what you cannot reproduce. 1. Run the failing case and capture the exact output (error message, stack trace, wrong value) 2. Determine reproducibility: always / intermittent / environment-dependent 3. Reduce to the smallest reliable reproduction (smallest input, fewest steps) 4. Record the reproduction command — every later hypothesis test reruns exactly this If the bug is intermittent, do NOT proceed as if it were deterministic. Run the repro N times to estimate frequency first; otherwise "the fix worked" is indistinguishable from "it didn't fire this time." ## Phase 1: Gather Evidence Collect facts before forming opinions: ```bash # What changed recently? Most bugs are regressions. git log --oneline -15 git diff HEAD~5 --stat # Find when it broke (when a good commit is known) git bisect start <bad> <good> # Read the actual error — the full stack trace, not the last line # Check logs around the failure timestamp ``` - Read the failing code path top to bottom — do not skim - Check assumptions at the boundary: actual input values, env vars, config, dependency versions - For Claude Code hook/tooling issues, check `~/.claude/logs/` #