vignesh2027 Overview
Debugging is a skill, not luck. Effective debugging is systematic: form a hypothesis, design a minimal test, validate or falsify, repeat. Random changes are not debugging — they are gambling.
When to Use
- When a test is failing and the cause is unclear
- When behavior in production differs from behavior in development
- When you've been debugging the same issue for more than 30 minutes
Process
Step 1: Reproduce reliably
Before investigating: reproduce the issue consistently. If you can't reproduce it, you can't verify you've fixed it.
Step 2: Gather evidence
Read the full error message (not just the last line). Check: logs, stack traces, metrics, recent changes. What changed recently?
Step 3: Form a hypothesis
Write down a specific, falsifiable hypothesis: "I believe the error is caused by X because of Y."
Step 4: Isolate the smallest reproduction
Create the simplest possible test case that reproduces the issue. Remove everything that is not necessary for the bug to manifest.
Step 5: Test the hypothesis
Design an experiment that will either confirm or falsify your hypothesis. This often means: add a log statement, write a unit test, or add an assertion.
Step 6: Falsify or confirm
If the evidence falsifies your hypothesis: form a new hypothesis. If it confirms: find the root cause (not just the symptom).
Step 7: Fix and verify
Fix the root cause, not the symptom. Verify the fix: the minimal reproduction must no longer reproduce. The full test suite must pass.
Step 8: Write a regression test
Write a test that would have caught this bug. Add it to the test suite.
Anti-Rationalizations
"I'll try changing this and see if it works" This is not debugging. Form a hypothesis first.
"The bug is intermittent — I can't reproduce it" Intermittent bugs have causes. Add logging and wait for the next occurrence. Or: analyze the conditions under which it occurred and stress test those conditions.
Verification Requirements
- Issue reproducible before fix attempted
- Root cause identified (not just symptom addressed)
- Fix verified with minimal reproduction
- Regression test added