6.4 Debugging Techniques

Debugging is not "change a line and see what happens." Professional debugging is an investigation: reproduce the symptom, narrow the scope, form hypotheses, gather evidence, verify the fix, and leave a regression guard behind.

The more complex the issue, the more you need to turn guesses into observable evidence.

Reproduce Before Explaining

If a defect cannot be reproduced, the team can spend hours trading guesses. Reproduction does not always mean 100% reliability, but it should at least identify trigger conditions, input, environment, time window, and observation method.

A useful reproduction note includes:

• Minimal steps.
• Input data.
• Environment and version.
• Expected result and actual result.
• Logs, screenshots, request IDs, or trace IDs.
• Variables that are still uncontrolled.

The smaller the reproduction, the smaller the search space.

Hypotheses Must Be Falsifiable

"Maybe it is cache" is not a complete hypothesis. A better version is: "If the CDN cache causes this, bypassing the CDN should show the latest avatar; if it still shows the old one, this direction is unlikely."

A good hypothesis comes with a low-cost experiment:

• What should we observe?
• What does result A imply?
• What does result B rule out?
• Which search space becomes smaller?

Bisection, Logs, And Minimization

When the search space is ordered, you can bisect it. Commit history, configuration ranges, input sizes, and dependency versions can all be split into a good side and a bad side. Binary debugging is powerful because each experiment cuts away a large part of the space.

Logs and observability help you see what happened inside the system. Good logs are not random prints everywhere. They record important boundaries: request entry, state change, external call, retry, exception, and user-visible result.

After the fix, do not just say "it works now." Also:

• Add a regression test or monitor.
• Explain the root cause and trigger.
• Remove temporary debug code.
• Record which hypotheses were ruled out.

Debugging is not about winning an argument. It is about letting facts make the system understandable again.