debugging-systematic

Systematic Debugging Methodology

Core Principle

Debugging is not guessing. It is a scientific process: observe the symptom, form a hypothesis, predict the outcome of a test, and run the test. Repeat until the root cause is found.

---

The Scientific Debugging Method

Step 1: OBSERVE — Gather Evidence

Before changing anything, collect all available information.

Checklist:

• Read the FULL error message, not just the first line.
• Read the FULL stack trace. Identify the frame in YOUR code (skip framework internals).
• Note the exact input / request / action that triggered the bug.
• Note the expected behavior vs. the actual behavior.
• Check logs (application logs, server logs, browser console).
• Note the environment (OS, runtime version, dependency versions, config).
• Check if the bug is reproducible. If not, note the frequency and conditions.

Key question: Can I reproduce this bug reliably? If not, gathering more observations is the priority.

Step 2: HYPOTHESIZE — Form a Theory

Based on the evidence, propose a specific, falsifiable explanation.

Good hypothesis format:

"The crash occurs because user.profile is null when the user has not completed onboarding, and line 47 accesses user.profile.name without a null check."

Bad hypothesis:

"Something is wrong with the user object."

Rules:

• The hypothesis must explain ALL observed symptoms.
• If it only explains some symptoms, it is incomplete — keep refining.
• Generate multiple competing hypotheses and rank by likelihood.

Step 3: PREDICT — Design an Experiment

Before touching the code, predict what you will see IF your hypothesis is correct.

Examples:

• "If the null profile hypothesis is correct, then logging user.profile on line 45 will print null for users created after January 1."
• "If the race condition hypothesis is correct, then adding a 500ms delay before the second call will make the bug disappear."

Step 4: TEST — Run the Experiment