The most expensive stage of an incident is often not the fix. It is the moment when everyone proposes an explanation at once: perhaps the network, perhaps the cache, perhaps the version that just shipped. Every guess sounds reasonable, but none of them moves the team closer to the facts.

Effective debugging is not about proving yourself right as quickly as possible. It is about eliminating incorrect explanations at the lowest possible cost.

1. Write the symptom as a falsifiable statement

“The page is slow” cannot be tested directly. Rewrite it:

In version 3.4.0, Android 14 users opening the detail page for the first time saw P95 time-to-interactive rise from 1.2 seconds to 3.8 seconds. Repeated visits did not show the same increase.

The statement identifies a version, platform, trigger, metric, and control case. The clearer the boundary, the fewer variables the team has to inspect.

2. Build one shared timeline

Place important events on the same clock:

10:02  Version rollout begins at 5%
10:07  API P95 remains stable
10:11  Client first-screen latency alert fires
10:14  Image CDN hit rate drops
10:18  Rollout expansion stops

Correlation is not causation, but time order quickly removes impossible explanations. A change that occurred after the symptom cannot be its original cause.

3. Change one variable at a time

A good experiment makes competing explanations produce different results. For example:

  • Disable image prefetch in the new version while keeping every other setting unchanged.
  • Compare the same request through a cache hit and a cache miss.
  • Use one device to compare a first visit with another visit after clearing local state.

If three features are rolled back at once and the problem disappears, the team still does not know which change mattered.

4. Search for counter-evidence deliberately

After choosing a hypothesis, ask: “If this is wrong, what should I observe?”

Suppose image decoding is believed to block the main thread. Lower-resolution images should then reduce the stall. If replacing the images does not change the metric at all, the hypothesis should lose priority.

Counter-evidence prevents a team from investing too much time in the first explanation that feels convenient.

5. Leave a safeguard after the fix

Every incident should create at least one lasting asset:

  • An automated test covering the critical path
  • A metric or alert that detects the change earlier
  • A reusable diagnostic script
  • A review that records the trigger and decision process

Without one of these, the issue has only been postponed rather than solved.

A compact checklist

[ ] Does the symptom include scope, a metric, and a control?
[ ] Are recent changes ordered on one timeline?
[ ] Does the current experiment change only one variable?
[ ] Does the hypothesis have an explicit disproof condition?
[ ] Does the fix explain every known observation?
[ ] Did we add a test, signal, script, or document?

Debugging is not an intuition contest. It is an engineering process for compressing uncertainty: every step should reduce the number of possibilities and increase the amount of evidence.