Skip to content
Testing

Systematic Debugging

Investigate a reproducible failure before choosing a code change.

Install with Skills CLI
npx skills add obra/superpowers --skill systematic-debugging

What it does

Repeated speculative fixes can obscure the original problem and introduce new failures. This skill gives the agent a staged debugging process that gathers evidence, compares working behavior, and tests a focused explanation.

What changes after install

  • Starts with errors, reproduction steps, and recent changes.
  • Traces data across component boundaries to locate the failing layer.
  • Tests one hypothesis before applying a minimal root-cause fix.

Install

Run this command with Node.js 22.20 or later and select your agent in the Skills CLI.

Install with Skills CLI
npx skills add obra/superpowers --skill systematic-debugging

Before using Systematic Debugging

  • Provide a reproducible failure, relevant logs and access to the affected code and environment. Be able to run a focused reproduction to test the suspected cause.

Read the reviewed setup instructions for the selected workflow.

When to use it

  • Diagnosing a failing test, build, or reproducible application defect.
  • Investigating a problem that crosses several services or processing stages.

When not to use it

  • Applying repeated unrelated patches without checking what each one proves.

Describe the failure before proposing a fix

A useful bug report includes the command or interaction, expected behavior, actual result, relevant logs, and when the behavior last worked. For example, if a local build succeeds but continuous integration fails, compare the runtime version, dependency installation, environment configuration, and exact failing step before changing application code.

The upstream workflow divides investigation into evidence gathering, comparison with working examples, hypothesis testing, and implementation. For a multi-component flow, it recommends examining what enters and leaves each boundary. That helps distinguish an input problem from a transformation problem or a missing output.

Keep experiments small

Ask the agent to state one explanation that fits the evidence and one check that would support or contradict it. Changing three unrelated settings at once can produce a green run without revealing which change mattered. If the explanation fails, update it rather than stacking more fixes on top.

Diagnostic work also needs appropriate access to logs and a safe reproduction environment. Avoid copying secrets or unrelated private data into bug reports. The skill provides a method; it cannot recover evidence that the environment never recorded.

Verify the original symptom

After a targeted change, repeat the failing case and check related behavior. A build passing does not necessarily show that an intermittent application defect is gone. Add a regression check where the behavior can be represented reliably.

Use Test-Driven Development for the regression cycle once the intended behavior is clear. Use this skill when the cause is still uncertain. SkillDex reviewed the upstream workflow and has not run a production incident investigation with it.

FAQ

Does this skill need a test suite?
A test suite helps, but the initial requirement is a reliable reproduction and evidence. A targeted script or manual reproduction may be the starting point.
What if the failure is intermittent?
Gather enough context and diagnostic evidence to understand when it occurs instead of assuming a successful rerun proves it is fixed.