systematic-debugging

# Systematic Debugging When stuck, stop guessing. Run the loop. Random edits that "might fix it" waste turns and mask the real cause. For known tool/git/CI failures, check the Error Patterns skill first — this skill is for novel bugs. ## The Loop 1. **Reproduce.** Get a reliable, minimal repro before changing anything. A bug you cannot reproduce on demand, you cannot confirm fixed. Note the exact command, inputs, and expected-vs-actual. 2. **Isolate.** Shrink the surface. Remove inputs, comment out code, halve the data until the smallest thing that still fails remains. `git bisect` when a regression has a known-good past commit. 3. **Hypothesize.** State ONE specific, falsifiable cause: "X is null because Y runs before Z." If you cannot name a mechanism, you are still guessing. 4. **Test the hypothesis.** Add a log/breakpoint/assertion that the hypothesis predicts. Observe. Confirm or kill it before touching the fix. 5. **Fix the root cause.** Not the symptom. If the fix is "add a null check," ask why it is null — that is usually the real bug. 6. **Verify.** Re-run the repro from step 1. Then run the surrounding tests to confirm you broke nothing. A fix unconfirmed against the original repro is not a fix. ## Discipline - **Read the actual error.** Full message, full stack trace, top to bottom. The answer is in there more often than not. Don't skim to the first familiar line. - **One change at a time.** Change-everything-and-pray destroys the ...