A field guide to debugging deliberately

Begin with an observable difference

“The website is broken” is a report, not yet a useful test. Rewrite it: this request returns HTML but the caller expects JSON; this function returns zero but its input contains two positive amounts. Include the input, expected result and actual result. Keep your theory out of that first sentence.

If production works but development fails, compare execution environments before changing passwords or rewriting authentication. A small relevant difference often explains more than a broad refactor.

Make competing explanations

A hypothesis must predict evidence. If a token expired, a new token should behave differently. If a parser truncated a value, compare its length or a safe equality result without printing the secret. Prefer checks that do not expose personal data or modify production records.

Write two plausible explanations and choose an experiment that distinguishes them. Changing five settings may hide a symptom without identifying its cause. That uncertainty becomes tomorrow’s regression.

Reduce without destroying

A minimal reproduction preserves the failure while removing unrelated details. Replace personal records with synthetic fixtures, but keep relevant punctuation, lengths and ordering. Normalization can erase a bug. Stop reducing when removing one more detail makes it disappear.

Production is evidence, not a disposable lab. Use read-only checks first and approved test data for mutations. A debugging session should not create a larger incident.

Close the loop

Rerun the original failing case and a nearby failure case. A login handler should accept the right password and reject a wrong one. Then record what changed and what remains unverified.

Bookmark this essay and answer the checkpoint below. It is original SkillNexis content; no third-party book-hosting permission is implied or required.

Try it yourself

Enable JavaScript for this interactive activity. You can read all lesson explanations above without it.