# Systematic Debugging (systematic-debugging)

> Works through bugs in four phases, root cause investigation, pattern analysis, hypothesis testing and implementation, fixing causes, not symptoms.

- Category: [Testing & Debugging](https://www.myskills.tools/en/categories/testing-debugging/)
- Source: Community · Jesse Vincent
- Repository: https://github.com/obra/superpowers/tree/main/skills/systematic-debugging (commit bb92a77)
- SKILL.md: https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md
- Install command: `npx skills add obra/superpowers --skill systematic-debugging`
- License: MIT
- Compatible with: Claude Code, Codex, Cursor, Gemini CLI, OpenCode
- Permissions: read-repo ✓, write-files ✓, shell ✓, network ✗
- Status: Scan passed
- A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.

## Core rule

No fixes without root cause investigation first.

## Execution Phases

1. **Investigate the root cause** — Read errors fully, reproduce reliably and check recent changes; in multi-component systems log each boundary and trace bad values back to their source.
2. **Analyze the pattern** — Find similar working code in the codebase, read reference implementations completely, and list every difference from the broken code.
3. **Hypothesize and test** — State one hypothesis, test it with the smallest change and one variable at a time; if it fails, form a new one instead of stacking fixes.
4. **Fix the root cause** — Write a failing test first, make a single fix and verify it; after 3 failed fixes, stop and question the architecture with your human partner.

## Permissions (summarised from SKILL.md)

| Capability | Needed | Details |
|---|---|---|
| File writes | Required | Adds diagnostic logging, writes a failing test and applies a single fix. |
| Command execution | Required | Reproduces the issue, runs tests, and checks git diff and recent commits. |
| Network outbound | Not required | The workflow has no network steps. |

## SKILL.md frontmatter (YAML)

```yaml
---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---
```

Home: https://www.myskills.tools/en/ · URL: https://www.myskills.tools/en/skills/systematic-debugging/