debugging-mastery

Use the DEBUG framework—Define, Explore, Bisect, Uncover, Guard—to diagnose complex bugs across modules. This structured approach emphasizes root-cause analysis, hypothesis formation, and regression safety through minimal reproduction and automated verification.

Root-cause analysis identifies the underlying reason a bug occurs, not just its symptoms. The 5 Whys approach iteratively questions each answer to dig deeper; combined with fishbone diagrams, it uncovers systemic issues rather than surface-level fixes.

Git-bisect automates binary search through your commit history to pinpoint the exact change that broke functionality. This Bisect step isolates bugs in multi-file workflows and is essential when conventional debugging resists simple fixes.

Escalate to debugging subagents when bugs involve race conditions, timing issues, or span so many layers that manual investigation becomes intractable. The framework provides guidance on recognizing these signals and structuring handoff steps.

The Guard step uses regression testing templates and minimal reproduction cases to verify your fix doesn't break existing functionality. Automated verification ensures changes remain safe across all affected components.

Yes. The framework explicitly handles race conditions and timing issues through structured exploration, reproducibility requirements, and the Explore and Uncover steps designed for non-deterministic or intermittent bugs.