Skip to main content
Agent skillFirst-run guide

Systematic Debugging

A root-cause debugging loop for coding agents: reproduce, isolate, hypothesize, then change one thing — instead of shotgun patches.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Systematic Debugging when a test is red, a prod error is looping, or the agent keeps editing unrelated files. It forces a repro and a single hypothesis before a patch.

When not to use it

Skip it for greenfield scaffolding (use TDD or Skill Creator). Skip it when the task is a known refactor with tests already covering the change.

How to install

Where will you use it?

Install the publisher’s plugin

This installs a bundle that can include other skills. Choose this method or the manual alternative below; you only need one installation.

  1. Run these commands in Claude Code:

    Claude Code CLI
    /plugin install superpowers@claude-plugins-official
  2. Ask Claude Code to use Systematic Debugging on a small task and confirm that it loads. Check the setup requirements in the publisher’s guide if it cannot run.
Alternative: install the folder manually

Use these steps if you choose the manual folder method. If you installed the plugin above, skip this alternative.

  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/systematic-debugging/SKILL.md. For a shared project, commit the folder at .claude/skills/systematic-debugging/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

What supports this recommendation?

82/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
83/100
Practical detail
92/100
Source evidence
63/100
Source signals
88/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

Source reviewedExample execution recorded

Try one small task

Best first exercise: diagnose a reproducible boundary error before proposing a patch.

See actual outputs and execution limits →

What you need

  • A coding agent with the project files, an executable test command, and a reproducible failure.
  • The upstream Superpowers skill package installed for that agent.

Find why a function rejects a valid zero value.

First task prompt
Use systematic-debugging on this JavaScript behavior in a scratch project: function hasStock(value) { return Boolean(value); }. The intended contract is true for every non-negative integer, including 0, and false otherwise. Reproduce the zero case, trace the root cause, test one hypothesis, then propose the smallest fix with regression checks for 0, 7, -1, 1.5, null and the string "7". Show commands and observed results.

Expected result

A specification to check against, not output from an AI run.

A trace from the failing zero example to truthiness, followed by a narrow fix and boundary checks.

  • The report shows the zero case failing before the patch and passing afterward.
  • Both 0 and 7 are accepted; negative, fractional, null, and string values are rejected.
  • The cause is supported by an observed result and the final checks use the same contract.

Where this exercise stops

  • This tiny deterministic fixture does not test intermittent, distributed, or production failures.
  • If the issue cannot be reproduced, gather evidence before declaring a root cause.

Recorded example run

These files came from actual execution in a Codex session. They were produced and checked within the same session; this is scoped evidence, not independent review or a measured success rate.

Zero-value bug: observed failure, hypothesis and fix

Executed · Automated Codex exercise

Codex agent; Node.js 24.13.0, Python 3.12.3, Linux 7.0.0-1010-aws. Exact model version not exposed.

Executed the zero case against Boolean(value), traced the result to truthiness, compared one numeric-domain hypothesis against six fixtures, then changed one expression and reran the contract suite.

Download the actual outputs

Recorded checks and observations

  • Observed: Before the patch, the intended zero assertion failed with false !== true.
  • Observed: The observed hypothesis output shows Boolean truthiness differs from the specified non-negative-integer contract.
  • Observed: After the narrow fix, all six cases passed: 0, 7, -1, 1.5, null and string 7.
Scope, limitations and pinned sources
  • The agent read the pinned upstream instructions and used their prescribed tools. Native Claude skill loading and general cross-agent compatibility were not tested.
  • This is a tiny deterministic synthetic function, not an intermittent, distributed or production incident.
  • The checks cover the stated contract cases; no no-skill control or broader model benchmark was run.
  • The executor was Codex in this conversation; the exact model version was not exposed.
  • These examples do not represent independent human users, customer outcomes or a compatibility certification.
Read the execution record (JSON) →
Source and evidence

The upstream instructions informed this guide. The exercise and acceptance checks are an OpxSkills test recipe. Where a run is recorded, its actual outputs, environment and limits appear separately above. A recorded example does not establish general model compatibility or a success rate.

Source reviewed · Upstream revision 8ca22dba9a94

What this skill does

Agents patch symptoms. This skill makes them write down the failing signal, the smallest repro, and the check that would prove the fix — then edit.

Intended uses

  • A flaky test the agent "fixed" three times
  • A production error with a stack trace in-session
  • A regression after a large diff

Implementation notes

  • Do not accept a fix without a repro command.
  • If the agent cannot reproduce, stop editing and gather evidence.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.