Skip to content
SkillMixed2,220 tokens in use

systematic-debugging

A four-phase debugging process that finds the root cause before any fix is proposed.

322,762 stars on the repository MIT Licenseobra/superpowers · skills/systematic-debugging
/plugin install superpowers@claude-plugins-official
View source

Install command as written in the repository's README

Skill label

measured from its files

What installing systematic-debugging costs

21tokens idle
2,220tokens in use
5,201tokens, up to

Idle is what sits in context while the skill is installed. In use is its instructions, loaded when it runs. Up to adds the files its instructions link. Counts are approximate, made offline with cl100k_base.

Model dependence Mixed

Script-ledMixedModel-led

Scripts do part of the work and the model's judgement does the rest.

This describes the skill's structure, how much of it is scripts. It does not say how well it works. Scripts: condition-based-waiting-example.ts, find-polluter.sh.

Touches

shelldetectedwrites filesdetected

Declared tags come from the skill's frontmatter; detected ones from its scripts, its code blocks and the commands it names in inline code. This is detected, not audited.

How it scores

Quality

How well the skill is written, counted from its own files: its frontmatter, its steps, examples, stated output and constraints, its size and whether every file it ships is one it names.How we score it →
Excellent
  • Frontmatter12/15
  • Structure25/25
  • Examples15/15
  • Output15/15
  • Size15/15
  • Resources9/15

Security

Starts at 100 and loses points for each thing in the skill's files that a reader should look at first.How we score it →
Excellent
  • Runs shell commands−5

    does this on the machine, and the frontmatter does not say so

    SKILL.md, line 90

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Good
  • Development activity56
  • Maintenance68
  • Community64
  • Maturity36
  • Momentum40

Systematic Debugging sets one law: no fixes without root cause investigation first. The agent works through four phases: read the errors and reproduce the bug, find working examples and compare, form one hypothesis and test it with the smallest change, then write a failing test and fix the cause. Supporting guides cover backward tracing, defense in depth and condition-based waiting.

What You Get

  • A four-phase process: root cause, pattern analysis, hypothesis, implementation
  • Techniques for tracing bad values back to their source
  • A defense-in-depth guide for validating at several layers
  • Condition-based waiting guidance with a TypeScript example for replacing arbitrary timeouts
  • A shell script that bisects test files to find the one that pollutes state

Common Use Cases

  • Investigating a failing test
  • Diagnosing a bug that spans several components
  • Tracking down a flaky test caused by timing
  • Finding the test that leaves stray files behind

What Makes It Unique

It forbids fixes until Phase 1 is complete and names the situations where agents are most tempted to skip it, such as time pressure and repeated failed fixes. A failed hypothesis leads to a new hypothesis, and fixes are never stacked on top of each other.

Under The Hood

Instructions plus four reference files and a bash script, find-polluter.sh, that loops over test files matched by a pattern and checks whether a given file or directory appears. The agent runs your build, test and diagnostic commands and reads git history and logs. The skill ships a TypeScript example for waiting on conditions.

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers