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