debugging-systematically

Systematic debugging follows three phases: reproduce the issue with minimal steps, narrow down the failure point using binary search and strategic logging, then apply a minimal fix. Document hypotheses and test each one against evidence before changing code.

Intermittent failures usually indicate race conditions, initialization order issues, or environment differences. Document exact reproduction conditions and frequency, then test hypotheses about state and timing while adding strategic logging at decision points.

Common bug patterns fall into four categories: type-related bugs like null handling and type mismatches, state-related bugs like race conditions and stale data, logic bugs like off-by-one errors, and integration bugs like API contract violations.

Minimal fixes reduce the risk of introducing new bugs and keep changes traceable for review. Refactoring during a fix mixes concerns, makes rollback harder, and obscures which change actually resolved the root cause.

For trivial typos or obvious syntax errors caught by linters, a full investigation framework adds unnecessary overhead. The methodology is most valuable for non-obvious bugs, intermittent failures, and issues spanning multiple components.