systematic-debugging

# Systematic Debugging ## Overview Random fixes waste time and create new bugs. Quick patches mask underlying issues and usually force a second debugging cycle. **Core principle:** ALWAYS find root cause before attempting a permanent fix. Symptom fixes are failure. **Debugging report quality is part of the job.** A report that lists guesses without evidence is not a passing debugging result. ## The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` If you haven't completed Phase 1, you cannot propose fixes. ### Diagnostic Instrumentation Exemption Adding temporary code to collect evidence is **NOT a fix**. The following are explicitly permitted during Phase 1 investigation: - Print/log statements to trace data flow (`fmt.Println`, `console.log`, `print()`, `logging.debug()`) - Temporary breakpoints or debug flags - Probe scripts that exercise a specific code path - Temporary test harnesses to isolate behavior - System commands (`df -h`, `lsof`, `strace`, `tcpdump`) to observe runtime state **Rules:** - Mark all diagnostic code clearly (e.g., `// DEBUG-INVESTIGATION` or `# DIAG`) - Remove or revert all diagnostic instrumentation after root cause is identified - Diagnostic code must not change program behavior — it only observes ## When to Use Use for ANY technical issue: - Test failures - Bugs in production - Unexpected behavior - Performance problems - Build failures - Integration issues - Flaky tests - Race conditions - Configuration drift - Third-...