Systematic Debugging

Guessing at fixes wastes more time than it saves — a plausible-looking patch that doesn't address the real cause just resurfaces the bug later, often in a harder-to-trace form. This skill is a fixed four-phase loop.

Phase 1: Reproduce

Get a reliable, minimal reproduction before touching any code. If you can't reproduce it, you don't have a bug yet, you have a report — go gather more information (logs, exact input, exact steps) instead of guessing.

Phase 2: Understand

Read the actual error, the actual stack trace, the actual code path — not the code you assume is there. Check what changed recently (git blame / git log on the affected file) if this is a regression. Trace the data: what was the value at each step, and where does it diverge from expected?

Phase 3: Hypothesize and isolate

Form ONE hypothesis for the root cause. Test it by changing exactly one variable — not by changing three things and seeing if it works now. If the hypothesis is wrong, you learned something specific; form the next one from that, don't just try a different random fix.

Phase 4: Fix and verify

Write a failing test that reproduces the bug, then make the minimal change that fixes the root cause (not a downstream symptom). Confirm the new test passes and the full existing test suite still passes.

The rule

No code change before Phase 2 is complete. "I have a hunch" is not the same as "I understand the root cause" — hunches are where Phase 3 starts, not where Phase 4 does.