34 lines
1.8 KiB
Markdown
34 lines
1.8 KiB
Markdown
---
|
|
name: systematic-debugging
|
|
description: Use when debugging complex bugs, unexpected test failures, race conditions, or production anomalies. Enforces a rigorous scientific debugging method over trial-and-error edits.
|
|
---
|
|
|
|
# Systematic Debugging — The Scientific Method for Bug Fixing
|
|
|
|
## Core Discipline
|
|
Never guess, shotgun edit, or apply speculative fixes without proving the root cause. Follow the 5-phase scientific debugging loop.
|
|
|
|
## Phase 1: Reproduce & Isolate
|
|
1. **Deterministic Reproduction:** Create a minimal, self-contained test case or command that reliably reproduces the failure.
|
|
2. **Eliminate Variables:** Strip away unrelated components, mocks, or background noise.
|
|
3. **Capture Ground Truth:** Inspect actual inputs, outputs, error codes, and stack traces — do not rely on memory or assumptions.
|
|
|
|
## Phase 2: Formulate Hypotheses
|
|
1. Brainstorm candidate root causes based on observed behavior.
|
|
2. Rank hypotheses by likelihood.
|
|
3. For each hypothesis, define an empirical test: *"If hypothesis X is true, observing Y will yield Z."*
|
|
|
|
## Phase 3: Test Hypotheses (Binary Search & Instrumentation)
|
|
1. Add targeted logs, breakpoints, or assertion guards at key boundary points.
|
|
2. Use bisection (git bisect or code division) to narrow down when/where state deviates from expected invariants.
|
|
3. Invalidate or confirm hypotheses one by one.
|
|
|
|
## Phase 4: Root Cause Fix
|
|
1. Fix the underlying design flaw, invariant violation, or race condition — not just the symptom.
|
|
2. Verify that the fix does not break related code or introduce regressions.
|
|
3. Clean up all temporary debug logging and instrumentation.
|
|
|
|
## Phase 5: Regression Prevention
|
|
1. Commit the automated reproduction test (unit/integration test) alongside the fix.
|
|
2. Add explicit invariants or typing to prevent this class of bug at compile or boot time.
|