Systematic Debugging

What it does

Systematic Debugging is part of the Superpowers development framework. It prevents a common agent failure: making several plausible edits without finding where the bad state originates. The workflow separates investigation, comparison with working behavior, hypothesis testing and implementation. Installing the whole framework can enable additional workflows; this guide describes the selected debugging skill.

When to use it

• A test or build fails with an unclear cause.
• An integration behaves differently locally and in CI.
• Several attempted fixes changed the symptoms without resolving the defect.

Step-by-step workflow

1. Read the full error and reproduce the failure with exact steps.
2. Inspect recent changes and collect evidence at the component boundary where behavior diverges.
3. Compare with a working case and trace the incorrect value back to its origin.
4. State one specific hypothesis and test the smallest change that can confirm or reject it.
5. Add a failing regression check, fix the verified cause and rerun relevant tests; repeated failed fixes require revisiting assumptions.

Example request

Use systematic-debugging to investigate why our CI build fails while the same command passes locally. Reproduce the failure, compare configuration and dependency versions, and gather only nonsecret diagnostic evidence. State one hypothesis at a time. Add a regression check where appropriate, then verify the smallest correction against the original failing command.

Worked example

A missing build variable can be introduced between CI configuration and the build subprocess. Checking only the final exception misses that boundary. Trace whether the configuration reaches the process without printing secret values; change the propagation only after that evidence identifies the break.

What you get

A reproducible failure, evidence-backed diagnosis, focused correction and verification result.

How to evaluate the result

• Confirm the requested artifact or behavior is actually delivered, with evidence appropriate to this workflow.
• Repeat the example on your own inputs and check the stated limits; repository popularity is not an execution test.
• Verify important facts, permissions and failure paths before adopting the result.

What you need

Failure output, reproduction steps, relevant source and access to the affected environment.

Setup and activation

Follow the publisher README for your specific client and preserve the complete selected skill folder, including companion references and scripts. Claude Code, Codex and other hosts may use different plugin or Agent Skills installation paths. This guide does not establish that every host has the same tools. Security-scan the exact version before installation; this website installs or executes nothing.

Limits and considerations

A root-cause workflow can reveal environmental or external failures rather than an application patch. Do not turn diagnostic collection into credential exposure. Broader Superpowers features and their permissions need separate review.

Related workflows

• Use a task-specific validation workflow to check the final result.
• Review companion scripts and references before adding this skill to an agent.

License and reuse

MIT at repository level; inspect per-file terms and separately licensed assets before reuse.

Further reading

• Publisher setup and compatibility instructions
• Reviewed skill version (immutable commit)