# Systematic Debugging

> Use when encountering any bug, test failure, or unexpected behavior. Four-phase root cause investigation. No fixes without understanding the problem first.

- Skill: `voidful/systematic-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add voidful/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/voidful/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: voidful (https://skillmd.com/u/voidful)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/voidful/systematic-debugging

---


# Systematic Debugging

## Core Principle

Random fixes waste time and create new bugs. **Always find the root cause before attempting fixes.**

## Phase 1 — Reproduce

Before anything else, reproduce the failure:

```bash
# Run the failing test or trigger the bug
cargo test <failing_test_name>
```

Record: exact error message, stack trace, which input triggers it.

## Phase 2 — Isolate

Narrow the scope:

- Is it a single function, a module boundary, or a data flow issue?
- Add `dbg!()` or `eprintln!()` at suspected boundaries.
- Check: does the bug appear in the most recent commit? Use `git bisect` if needed.

## Phase 3 — Understand

Before writing any fix:

- State the root cause in one sentence.
- Explain why the current code produces the wrong behavior.
- Predict what a correct fix would change.

If you cannot do all three, you have not finished Phase 3.

## Phase 4 — Fix and Verify

- Write a test that captures the root cause (this test should fail before the fix).
- Apply the minimal fix.
- Run the full test suite to check for regressions.

## When NOT to Use

- Typos and trivial syntax errors. Just fix them.
- Build configuration issues. Check `Cargo.toml` first.