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.
“Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes”
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.
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.
Not established by this review
- Source inspection only; no skill installation or workflow execution was performed.
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.
DOCUMENTED COMMAND
npx skills add https://github.com/obra/superpowers/tree/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debuggingCopying does not execute this command. It may retrieve a newer version than the reviewed source.
- Install the complete skill directory with its references and helpers; a copied SKILL.md alone may be incomplete.
- Choose the intended agent and project 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
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/SKILL.md
Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, compatibility, access
https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/root-cause-tracing.md
Supports: review, limitations, access
https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/systematic-debugging/find-polluter.sh
Supports: review, limitations, access
https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/LICENSE
Supports: license
https://github.com/obra/superpowers/blob/5bf4e78011075bcfc0dc295f0724994cd123ee71/README.md
Supports: install, compatibility, access
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts
Supports: install