systematic-debugging

Follow a four-phase process: first reproduce the issue reliably and record the reproduction rate, then isolate the source by checking recent changes and minimal cases, find the root cause with the 5 Whys technique, and finally fix and verify with a regression test.

Root cause analysis identifies the underlying reason a bug occurs rather than its surface symptoms. The 5 Whys technique asks "why" iteratively—typically five times—to move from the first observation down to the true originating cause.

Document exact reproduction steps and classify the reproduction rate as always, often, sometimes, or rare. Check recent git changes, compare environments, and reduce the failing scenario to the smallest code change that still triggers the issue.

Avoid making random changes hoping something works, ignoring contradictory evidence, assuming a cause without proof, fixing before reproducing the issue, and stopping at symptoms instead of finding the root cause.

Confirm the bug no longer reproduces, check that related functionality still works, ensure no new issues were introduced, and add a regression test. Also document the root cause and inspect similar code for the same defect.