---
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.