# Systematic Debugging

> Root-cause investigation discipline. Use before proposing fixes. The Iron Law: no fixes without Phase 1 complete.

**Skill · v1.0 · Updated 2026-04-29**

Systematic Debugging is a four-phase discipline for finding root causes before attempting fixes. The Iron Law: no fixes without Phase 1 complete. Use under time pressure especially, when guessing is most tempting.

## Install

### Claude Code (CLI / WSL / Git Bash)

```
/plugin marketplace add https://www.infinitegameos.io/marketplace.json
/plugin install systematic-debugging@igos-library
```

### Claude Code (VS Code)

[Install in VS Code](vscode://anthropic.claude-code/install-plugin?plugin=systematic-debugging&marketplace=https%3A%2F%2Fwww.infinitegameos.io%2Fmarketplace.json)

Opens the Claude Code plugins dialog with the marketplace and skill prefilled. Requires the Claude Code VS Code extension installed and signed in. Or paste the snippet below into `.claude/settings.json` for VS Code, JetBrains or any setup that prefers manual config:

```json
{
  "extraKnownMarketplaces": {
    "igos-library": {
      "source": {
        "source": "url",
        "url": "https://www.infinitegameos.io/marketplace.json"
      }
    }
  },
  "enabledPlugins": {
    "systematic-debugging@igos-library": true
  }
}
```

### Direct markdown URL

```
curl https://www.infinitegameos.io/markdown/skills/systematic-debugging
```

Or send `Accept: text/markdown` to https://www.infinitegameos.io/skills/systematic-debugging

### Cursor

```
curl -O https://www.infinitegameos.io/install/cursor/systematic-debugging.mdc
```

### Aider, Cline, any agent with --read

```
curl -O https://www.infinitegameos.io/markdown/skills/systematic-debugging
aider --read systematic-debugging.md
```

## Definition

Systematic Debugging is a root-cause investigation discipline applied to any technical issue: code bugs, integration failures, hook script errors, build failures, system malfunctions. Four phases run in sequence. Phase 1 identifies the root cause through error reading, reproduction, change tracking and evidence gathering. Phase 2 finds the pattern by comparing against working examples. Phase 3 forms a single hypothesis and tests it minimally. Phase 4 implements one targeted fix and verifies. The Iron Law applies: no fixes without Phase 1 complete. Three failed fix attempts indicates an architectural problem, not a fourth fix.

## The Iron Law and the four phases

The Iron Law: no fixes without root cause investigation first. Seeing symptoms is not understanding root cause. Phase 1 is non-negotiable. Phase 2 finds the pattern by locating working examples and identifying every difference, however small. Phase 3 forms exactly one hypothesis and tests it with the smallest possible change. One variable at a time.

Phase 4 implements the single fix and verifies. If the fix does not work, return to Phase 1 with new information. After three failed attempts, stop and question the architecture. The pattern signals are clear: each fix reveals new coupling in a different place; fixes require major structural changes; each fix creates new symptoms elsewhere. That is wrong architecture, not a failed hypothesis.

## Use Cases

**Production bug under time pressure**

A production bug surfaces during a high-stakes window. The temptation is guess-and-check. Systematic Debugging applies its Iron Law: Phase 1 first. Evidence gathering at component boundaries surfaces the actual root cause in minutes; the targeted fix in Phase 4 resolves cleanly without introducing new symptoms.

**Multi-layer integration failure**

A hook script calls a service that calls an external API. Something breaks; the symptom is at the top of the stack. Phase 1 step 4 (multi-component evidence gathering) instruments each boundary to log entry/exit data. The failing component surfaces from the evidence rather than from a guess.

**Architectural problem masquerading as a bug**

Three fixes have been attempted. Each one revealed a new problem. Systematic Debugging recognizes this pattern: this is not a failed hypothesis, this is a wrong architecture. The skill stops the fix loop and surfaces the architectural question to the operator before attempting a fourth fix.

## FAQ

**Is this overkill for simple bugs?**

No. Simple bugs have root causes too, and the process is fast for simple cases. The discipline is the same whether the bug is small or large; the time spent in each phase scales with complexity. Skipping Phase 1 on simple bugs creates the habit that fails on hard ones.

**What if the fix is obvious?**

Verify it is obvious by completing Phase 1 quickly. Often what looks obvious is a symptom, not the root cause. The Iron Law applies even when the answer feels certain. Quick Phase 1 confirms or redirects.

**What does it mean when 3 fixes have failed?**

It means the architecture is wrong, not the hypothesis. Stop attempting fixes. Surface the architectural question to the operator. A fourth attempt without that conversation creates more debt and moves further from resolution.

## Related

- [Source Harvest](https://www.infinitegameos.io/skills/source-harvest)

---

Systematic Debugging is one entry point. The wider operating system that uses it is Infinite Game OS. The full life-design frame that motivates clean architecture in the first place is the Sovereign Life Playbook.

[See the Sovereign Life Playbook](https://sidequesthq.co/products/sovereign-life-playbook)

---
*[Infinite Game OS](https://www.infinitegameos.io) · [Skills](https://www.infinitegameos.io/skills) · [Systematic Debugging](https://www.infinitegameos.io/skills/systematic-debugging)*