# Systematic Debugging

> Investigate bugs, test failures, and unexpected behavior through root-cause analysis before proposing fixes. Use when encountering any technical issue.

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

---


# Skill: Systematic Debugging

This skill enforces root-cause investigation before any fix attempt. Random fixes waste time and create new bugs.

---

## When to Use

Use for any technical issue:

- Test failures
- Bugs in production or development
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

Do **not** skip this skill when:

- The issue seems simple (simple bugs have root causes too)
- You are under time pressure (systematic debugging is faster than thrashing)
- A fix seems obvious (obvious fixes often mask the real problem)

---

## Execution Model

- **Primary agent** runs this skill directly.
- **Rationale**: Debugging requires iterative investigation in the same context. Delegating to a subagent loses the accumulated understanding.
- **Exception**: For multi-component issues spanning independent subsystems, delegate per-subsystem investigation to separate agents via the `dispatch-parallel-agents` skill.

---

## Workflow

### Phase 1: Root Cause Investigation

**No fixes are allowed until this phase is complete.**

1. **Read error messages carefully** -- stack traces, line numbers, error codes. Do not skip past them.
2. **Reproduce consistently** -- determine the exact steps. If not reproducible, gather more data instead of guessing.
3. **Check recent changes** -- `git diff`, recent commits, new dependencies, config changes, environmental differences.
4. **Gather evidence at component boundaries** -- for multi-layer systems (CI -> build -> deploy, API -> service -> database), add diagnostic logging at each boundary to identify where the failure occurs.
5. **Trace data flow** -- follow the bad value backward through the call stack to its origin. Fix at the source, not at the symptom.

### Phase 2: Pattern Analysis

1. **Find working examples** -- locate similar working code in the same codebase.
2. **Compare against references** -- if implementing a pattern, read the reference implementation completely. Do not skim.
3. **Identify differences** -- list every difference between working and broken code, however small.
4. **Understand dependencies** -- what components, settings, config, and environment does this code need?

### Phase 3: Hypothesis and Testing

1. **Form a single hypothesis** -- state clearly: "I think X is the root cause because Y."
2. **Test minimally** -- make the smallest possible change to test the hypothesis. One variable at a time.
3. **Verify before continuing** -- if the hypothesis is wrong, form a new one. Do not stack fixes.
4. **Acknowledge unknowns** -- if you do not understand something, say so. Do not pretend.

### Phase 4: Implementation

1. **Fix the root cause, not the symptom.**
2. **One change at a time** -- no "while I'm here" improvements, no bundled refactoring.
3. **Verify the fix** -- run the relevant tests, confirm the issue is resolved, confirm no regressions.
4. **If 3+ fixes have failed** -- stop. The issue is likely architectural, not a bug. Discuss with the user before attempting more fixes.

---

## Rules

1. **No fixes without investigation**: Phase 1 must be complete before proposing any fix.
2. **One hypothesis at a time**: Do not apply multiple changes simultaneously.
3. **Evidence over intuition**: Every fix must be justified by evidence from the investigation, not by "it might work."
4. **Escalate after 3 failed attempts**: Three failed fixes indicate an architectural problem. Stop fixing and discuss with the user.
5. **Do not increase timeouts as a fix**: Find the real timing issue instead.
6. **Read error messages completely**: Stack traces contain the answer more often than not.