A test fails unexpectedly
Read the complete failure and compare it with a nearby passing case before changing the code.
Systematic Debugging by Jesse Vincent
Use Systematic Debugging from Superpowers to investigate a failure before proposing repairs. Reproduce the behavior, compare working and broken paths, test a specific explanation, and verify a root-cause correction rather than stacking speculative changes on top of an unresolved problem.
Install and get started
Choose your agent to see how to get started. In Floatboat, copy a request that asks the agent to read the original instructions. Other options show the Skill installation command or the publisher’s native setup steps.
Choose an agent
Start in Floatboat
Copy the request into a Floatboat conversation
Read the original Systematic Debugging instructions at https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md. Explain its purpose, required tools, and installation options, then help me use it.Let the agent read the original instructions and check how to use them in your environment.
Download Floatboat ↗Try this request
Use Superpowers Systematic Debugging for the CI-only build failure. Compare environment propagation across the pipeline before proposing a fix, then verify the original job.
About Systematic Debugging
Systematic Debugging is Superpowers’ root-cause investigation Skill, maintained by Jesse Vincent and the project’s contributors. Its four phases cover evidence gathering, pattern comparison, hypothesis testing, and implementation. It asks the agent to read errors, reproduce the failure, inspect recent changes, and observe data across component boundaries before choosing a fix. A small test checks one explanation at a time; the implementation stage uses a failing reproduction and verification. Repeated failed repairs call for an architectural discussion rather than another blind change. The full workflow references companion testing and completion-verification skills, and it still depends on access to the environment where the problem occurs.
Use Cases for Systematic Debugging
Explore failures where a visible symptom does not yet explain the cause. Diagnose a failing test, trace a build or integration error through multiple components, or revisit a problem after unsuccessful fixes while using evidence to keep each proposed change tied to one testable explanation.
A pipeline fails between components
Inspect what enters and leaves each boundary to identify the layer that actually breaks.
Several attempted fixes failed
Revisit assumptions and discuss architectural causes instead of adding another untested patch.
How to Investigate a Failure Systematically
Provide the exact error, expected behavior, and reproduction environment, then work through evidence gathering and pattern comparison. Test one hypothesis with a minimal change, implement the supported correction, and use the companion verification discipline to confirm the symptom and relevant tests are resolved.
- 01
Collect evidence and patterns
Reproduce the error, inspect recent changes, and compare a working path. Add targeted boundary observations when several components are involved.
- 02
Test one explanation
State a specific hypothesis and use the smallest useful test. Change one variable and evaluate the result before choosing another explanation.
- 03
Implement and verify the cause
Capture a failing reproduction, apply the supported fix, and rerun relevant checks. Escalate repeated failures into a design discussion.
Explore More Agent Skills
Read another Skill guide and check its original source before using it.
Systematic Debugging FAQ
How is this different from Diagnosing Bugs by Matt Pocock?
They are separate workflows from different publishers. Superpowers organizes the process into four phases with companion testing and verification; Matt’s current workflow places particular emphasis on a tight red-capable feedback loop and minimized reproduction.
Can I apply the obvious fix immediately?
The Skill asks for root-cause investigation first. A plausible edit is not evidence; establish why it addresses the observed failure and verify that behavior.
What are the four phases?
They are root-cause investigation, pattern analysis, hypothesis testing, and implementation. Each stage supplies evidence for the next.
What should happen after several failed fixes?
The source calls for stopping and questioning the architecture after three or more unsuccessful fixes, rather than continuing with another speculative patch.
Which companion skills does it reference?
The implementation stage points to test-driven-development for failing tests and verification-before-completion for checking the final result. Use the Superpowers integration to keep them available.
Does a passing test always prove the issue is fixed?
Check that the test reproduces the user’s actual symptom and that the original flow works afterward. A nearby passing condition can miss the root failure.
Can it debug without access to the failing environment?
It can organize the investigation, but missing reproduction evidence limits the conclusion. Provide suitable redacted logs or a representative environment and keep unsupported explanations labeled as hypotheses.
How do Codex App and Codex CLI installation differ?
Codex App uses the Plugins sidebar: locate Superpowers in Coding, click +, and follow the prompts. Codex CLI uses /plugins to search for Superpowers and select Install Plugin. These are two interfaces for the official plugin marketplace.