Changing suspicious code until an error disappears can produce a green result without explaining what happened. Systematic-debugging structures the investigation so the eventual fix addresses an observed cause rather than an attractive guess.
Install and start
Run the following plugin command inside a Claude Code session to install Superpowers, including its cooperating skills. In Codex, find Superpowers in the plugin interface and install it there. Install separately for each client you use. Start a fresh session in the project and explicitly ask to use systematic-debugging with a bounded task.
/plugin install superpowers@claude-plugins-official
Describe the failure precisely
Adapt this first request to your project:
Use Superpowers systematic-debugging. Order tests pass locally but fail a timezone assertion in CI. Inspect the complete failure, CI configuration, and relevant changes; reproduce it or collect useful evidence. Test one hypothesis at a time. Do not start by raising timeouts or removing assertions. Add a regression test and a minimal root-cause fix.
Include the complete error, reproduction steps, expected behavior, actual behavior, and recent relevant changes. The final log line may omit the important call chain. For local-versus-CI differences, compare runtime versions, timezone or locale settings, fixtures, and commands before deciding the environment is simply unreliable.
Gather evidence at boundaries
Begin by reproducing the failure consistently. If reproduction is not yet possible, add observations that distinguish plausible causes. For a path crossing a client, API, and database, inspect the relevant input, output, and failure point at each boundary to identify where behavior first diverges.
Find a comparable path that works and explain its differences. Then state one falsifiable hypothesis, such as a date being interpreted differently under two timezone settings, and test it with the smallest useful experiment. Changing several variables together makes even a passing result difficult to interpret. Diagnostic logging should expose the necessary evidence, not indiscriminately print credentials or customer data.
Repair the cause and preserve the regression
Once the cause is understood, encode the failing condition as a regression test. Observe that it fails for the intended reason before modifying the implementation. Make the smallest correction that addresses the cause, then run the relevant checks and the broader verification appropriate to the project.
The report should connect cause, evidence, change, and remaining coverage. The upstream process calls for reconsidering architectural assumptions after repeated unsuccessful fixes. If three attempts merely move the failure somewhere else, discuss the underlying design instead of stacking another patch.
An external dependency can be the cause, but retries, monitoring, or timeouts should follow evidence rather than replace investigation. A useful result enables another developer to reproduce the original failure and understand why the correction is appropriate. The skill provides a disciplined process, not a promise that every defect can be solved in one session. When the environment is insufficient, identify the next evidence needed instead of inventing certainty.
Another example: find the layer that duplicates a charge
For a report that one click produced two charges, protect sensitive data and trace both transactions through request IDs, order IDs, timestamps, and redacted logs. Compare browser requests, gateway behavior, the application service, and the payment API. Did the browser send two requests? Did the gateway retry? Did the server create two payment intents for one order? These require different fixes; disabling the button alone cannot establish root cause. Find the first boundary where one operation became two.
Test a falsifiable hypothesis in isolation: did a timeout retry reuse the same idempotency key? Inspect request records, then simulate duplicate requests without charging a live account. Once the cause is clear, turn the expected behavior for a repeated order request into a regression test and repair that boundary. Check whether already affected orders need operational handling. If tests cover only local code, explicitly note the remaining uncertainty around third-party callbacks, network retries, or old data.
Add a postmortem for deployment incidents
Use the skill first to find a reproducible technical break: the step, input, and log line where behavior diverged. For a deployment incident, add a separate postmortem rather than treating a one-line fix as the complete root cause. One user initially received a flat list of symptoms after a deployment failure and later separated causes by timeline and by machine, material, people, and process. For a similar incident, record timeline, impact, direct technical failure, and systemic causes separately. Give each process cause a verifiable corrective action after fixing the code path.