---
title: "Superpowers Systematic Debugging: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/obra-systematic-debugging/
description: "Moves debugging from reproducible evidence through a single hypothesis to a verified fix, with a stop point for repeated failed attempts."
---

# Superpowers Systematic Debugging: review, setup & limitations · Undominated.ai

> Moves debugging from reproducible evidence through a single hypothesis to a verified fix, with a stop point for repeated failed attempts.

[← Explore all skills](/skills/)

TESTING AND RELIABILITY / Jesse Vincent / Superpowers

# Superpowers Systematic Debugging

Moves debugging from reproducible evidence through a single hypothesis to a verified fix, with a stop point for repeated failed attempts.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/obra/superpowers/tree/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging)

SOURCE REVIEW

 Reviewed 2026-10-14
 Evidence 8 linked sources
 Publisher Jesse Vincent / Superpowers
 Licence [MIT ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/LICENSE)
 Revision 5bf4e7801107
 [Read what was—and wasn’t—checked ↓](#review)

“Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes”

 [Jesse Vincent / Superpowers · upstream description ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Asks for evidence at component boundaries and backward tracing of bad values before proposing a patch.
- Treats repeated failed fixes as a reason to revisit the architecture rather than keep layering changes.

### A good fit for

 - Investigating a failure whose cause is unclear
- Separating a test-order pollution issue from a product regression
- Trace configuration or payload propagation across process boundaries before changing implementation
- Compare a failing implementation with a working example and test a single stated hypothesis by changing one variable at a time.

### Weigh up before choosing

 - The bundled polluter helper assumes npm tests, hides their output and swallows their failing exit statuses.
- It skips tests when the watched path already exists and is not robust to whitespace in test filenames.
- Diagnostic examples can print environment values; adapt them to avoid exposing credentials.
- The source claim that 95% of unexplained failures are incomplete investigation is unsupported by a cited measurement; do not repeat it as an observed rate.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - skills/systematic-debugging/SKILL.md
- skills/systematic-debugging/root-cause-tracing.md
- skills/systematic-debugging/find-polluter.sh
- LICENSE

### Our findings

 - The definition separates evidence collection, working-example comparison, hypothesis testing and implementation.
- The root-cause reference follows the origin of invalid state through callers instead of fixing only the final symptom.
- The inspected helper detects creation of a path, not general test success; no successful debugging run is claimed here.
- The four-phase procedure requires boundary evidence before fixes, single-variable tests and a root-cause reproduction; it also permits documented environmental handling when investigation remains inconclusive.

### Not established by this review

 - Source inspection only; no skill installation or workflow execution was performed.
- Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md)

DOCUMENTED COMMAND

 npx skills add obra/superpowers --skill systematic-debugging Copy command ↗

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

 Optional: install the reviewed revision

Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.

 npx skills add https://github.com/obra/superpowers/tree/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging Copy reviewed-revision command ↗ - Install the complete skill directory with its references and helpers; a copied SKILL.md alone may be incomplete.
- Choose your AI tools and project or global scope in the installer, then review its permissions before using the skill.

### Before you start

 - Node.js/npm for this installer
- An agent that supports the Agent Skills format
- A reproduction, relevant logs and permission to run the project’s checks

### Compatibility

Superpowers-supported coding agents · The optional polluter helper assumes Bash and npm

### Read source, logs and recent changes

 - Read source, logs and recent changes
- Add temporary diagnostic instrumentation
- Execute project tests and inspect filesystem side effects
- May add temporary diagnostic instrumentation and execute reproductions that inherit application side effects.

### Cost model

The MIT-licensed process uses the configured agent and local or external test resources.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Skill definition at reviewed revision ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/SKILL.md) Checked 2026-10-14 https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/SKILL.md Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, compatibility, access
- [Reviewed reference or helper: root-cause-tracing.md ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/root-cause-tracing.md) Checked 2026-09-21 https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/root-cause-tracing.md Supports: review, limitations, access
- [Reviewed reference or helper: find-polluter.sh ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/find-polluter.sh) Checked 2026-09-21 https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/find-polluter.sh Supports: review, limitations, access
- [Upstream license or licensing declaration ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/LICENSE) Checked 2026-09-21 https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/LICENSE Supports: license
- [Publisher installation and project documentation ↗](https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/README.md) Checked 2026-09-21 https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/README.md Supports: install, compatibility, access
- [Skills installer source formats and selective installation ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md) Checked 2026-09-21 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md Supports: install
- [Installer implementation: full commit SHA fallback ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts) Checked 2026-09-21 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts Supports: install
- [Pinned source review C2-W18 ↗](https://raw.githubusercontent.com/obra/superpowers/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/SKILL.md) Checked 2026-10-15 https://raw.githubusercontent.com/obra/superpowers/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/SKILL.md Supports: bestFor, review.notTested

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Diagnosing Bugs ↗ A debugging procedure that establishes a reproducible symptom, tests competing explanations and preserves a regression check.](/skills/mattpocock-diagnosing-bugs/)[### Bug Receipt ↗ Creates an evidence-bearing defect or incident handoff that distinguishes verified, partial and blocked outcomes.](/skills/github-bug-receipt/)[### Superpowers Receiving Code Review ↗ Checks review feedback against the code and project constraints before making and testing each requested change.](/skills/obra-receiving-code-review/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
