SKILL.md

v1.0.0 · 1739 B · text/markdown

---
name: systematic-debugging
description: Use when investigating any bug, crash, or unexpected behavior - a four-phase loop that stops guessing and forces root-cause understanding before a fix is written
---

# Systematic Debugging

Guessing at fixes wastes more time than it saves — a plausible-looking patch
that doesn't address the real cause just resurfaces the bug later, often in
a harder-to-trace form. This skill is a fixed four-phase loop.

## Phase 1: Reproduce

Get a reliable, minimal reproduction before touching any code. If you can't
reproduce it, you don't have a bug yet, you have a report — go gather more
information (logs, exact input, exact steps) instead of guessing.

## Phase 2: Understand

Read the actual error, the actual stack trace, the actual code path — not
the code you assume is there. Check what changed recently (git blame /
git log on the affected file) if this is a regression. Trace the data:
what was the value at each step, and where does it diverge from expected?

## Phase 3: Hypothesize and isolate

Form ONE hypothesis for the root cause. Test it by changing exactly one
variable — not by changing three things and seeing if it works now. If the
hypothesis is wrong, you learned something specific; form the next one from
that, don't just try a different random fix.

## Phase 4: Fix and verify

Write a failing test that reproduces the bug, then make the minimal change
that fixes the root cause (not a downstream symptom). Confirm the new test
passes and the full existing test suite still passes.

## The rule

No code change before Phase 2 is complete. "I have a hunch" is not the same
as "I understand the root cause" — hunches are where Phase 3 starts, not
where Phase 4 does.