dsh-skills/skills/systematic-debugging/SKILL.md

name, description

name	description
systematic-debugging	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.