systematic-debugging

Systematic Debugging

A structured approach to finding and fixing bugs.

The Debugging Loop

1. REPRODUCE → 2. ISOLATE → 3. DIAGNOSE → 4. FIX → 5. VERIFY

Never skip steps. Never guess-and-check repeatedly.

Step 1: Reproduce

• Run the exact command that fails
• Capture FULL output (stdout AND stderr)
• Note: exit code, error message, stack trace
• If intermittent, identify what changes between runs

Step 2: Isolate

• What's the MINIMAL input that triggers the error?
• Which specific line/function fails? (read the traceback bottom-up)
• Is it a compile error, runtime error, or wrong output?
• Does it fail on all inputs or specific ones?

Step 3: Diagnose

Read the error message carefully

Error type	Where to look
Compile error	The FIRST error (later ones are often cascading)
Segfault	Last function in the stack trace, check array bounds and null pointers
Python traceback	The innermost frame (bottom), but also check the middle for context
Wrong output	Diff expected vs actual: diff <(expected) <(actual)
Timeout/hang	Is it an infinite loop? Deadlock? I/O bound? Add a timer or counter

Add minimal instrumentation

• C: fprintf(stderr, "reached checkpoint %d\n", __LINE__);
• Python: print(f"DEBUG: {var=}", file=sys.stderr)
• Check intermediate values, not just final output
• Remove debug prints after fixing

Step 4: Fix

• Change ONE thing at a time
• If the same approach fails 3 times → completely different strategy
• Don't add workarounds — fix the root cause
• Common root causes:
  • Off-by-one errors (loop bounds, array indexing)
  • Type mismatches (int vs float, signed vs unsigned)
  • Encoding issues (UTF-8 vs bytes)
  • Path errors (relative vs absolute, missing trailing slash)
  • Race conditions (file not written yet, process not started)

Step 5: Verify

• Run the same command that failed before
• Test with multiple inputs, not just the one that was failing
• Check edge cases: empty input, single element, very large input
• Run any existing test suite

Common Failure Patterns

"It compiles but gives wrong output"

1. Print all intermediate values
2. Compare with a known-correct reference implementation
3. Check: integer overflow, floating point precision, endianness

"It works on small input but times out on large"

1. Check algorithm complexity — O(n²) on 1M items = timeout
2. Profile: which loop/function takes the most time?
3. Restructure: hash maps, sorting, streaming

"It works locally but fails in the test"

1. Check: absolute vs relative paths
2. Check: different working directory
3. Check: different input format than expected
4. Read the test script to understand what it actually checks