debugging-and-diagnosis

Systematic debugging follows a four-phase framework: collect evidence by gathering logs and reproducing the bug with precise steps, isolate variables to narrow down what changed, formulate hypotheses about the cause, and test/verify each hypothesis. This evidence-based approach ensures you identify root cause before implementing any fix.

The iron law of debugging is: no fixes without root cause first. Quick fixes mask underlying problems and often resurface later. Root-cause investigation prevents recurring bugs, reduces technical debt, and ensures fixes address the actual issue rather than its symptoms.

Collect evidence by documenting exact reproduction steps, environment details, and logs. Reproducibility is critical—narrow the scenario to the minimal steps that trigger the bug consistently. This precision enables isolating variables and testing hypotheses systematically rather than guessing.

After collecting evidence, isolate variables by testing individual components, changing one condition at a time, and reviewing logs for patterns. For intermittent issues, log contextual data to identify triggers. For performance problems, measure before and after each hypothesis test to confirm impact.

Yes. The four-phase framework applies to bugs, errors, crashes, unexpected behavior, failing tests, and intermittent performance or integration issues. Collect evidence from test output and logs, isolate the failing component, formulate hypotheses about the interaction or state, and verify fixes with end-to-end testing.

Track findings, hypotheses tested, test results, and evidence collected throughout each phase. Maintain end-to-end traceability so you can escalate findings if needed and document why a particular fix was chosen. This log supports reproducibility and helps others understand the investigation.