Debugging With Evidence

A stubborn bug invites storytelling. We see one suspicious line, imagine a chain of events, and begin changing code before confirming the first step. Occasionally the story is right. More often, the change removes a clue and creates a second mystery.

An evidence-first approach begins by making the failure repeatable. Record the smallest input that triggers it, the exact output you observe, and the environment where it occurs. These facts form a boundary around the problem.

Shrink the search space

Add one observation at the boundary between components: a test assertion, a structured log, or a direct inspection of stored data. Choose the result that would most clearly separate two competing explanations. Then repeat.

This process can feel slower than editing the suspected function immediately, but each result removes possibilities. Even a disproved hypothesis is progress when the experiment was precise.

Once the cause is known, preserve the evidence as a regression test. The final test should describe the behavior users depend on, not the accidental implementation detail that happened to break. That way the investigation continues to pay rent long after the bug is gone.