systematic-debuggingcommit bb92a77SKILL.md · Testing & Debugging
Systematic Debugging
Works through bugs in four phases, root cause investigation, pattern analysis, hypothesis testing and implementation, fixing causes, not symptoms.
npx skills add obra/superpowers --skill systematic-debuggingCommand selected. Copy it manually.
- Permissions
- read-repo
- write-files
- shell
- network
- Compatible with
- Claude Code, Codex, Cursor, Gemini CLI, OpenCode
- GitHub
- 310.3k
- Source
- Community · Jesse Vincent
- Status
- Scan passed
- License
- MIT
- Category
- Testing & Debugging
Core rule
No fixes without root cause investigation first.
Execution Phases
Phase 01Investigate 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.
Phase 02Analyze the pattern
Find similar working code in the codebase, read reference implementations completely, and list every difference from the broken code.
Phase 03Hypothesize 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.
Phase 04Fix 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)
---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---