systematic-debugging

An agent skill by obra, from obra/superpowers. Tags: api, debugging, developer-tools, web.

What it does

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add obra/superpowers --skill systematic-debugging

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/obra/superpowers
cp -r superpowers/skills/systematic-debugging ~/.claude/skills/systematic-debugging

Safety box score

Grade B, low risk: 19 of 100 risk points, rated 2026-10-20. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This is a debugging/process skill, not a deployment or data-exfiltration tool. The main risks are a helper script that repeatedly executes project tests and diagnostic examples that can expose sensitive environment or keychain data; the bundled pressure-test docs also contain prompt-injection-style wording.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	1 (low)	The shipped helper script runs project tests in a loop with `npm test "$TEST_FILE"`, which executes repository code but stays scoped to debugging tasks.
Network access	0 (none)	No file downloads, uploads, API calls, or remote-host communication are defined in the shipped skill files.
Filesystem reach	0 (none)	The skill reads local files and checks for test-generated pollution, but it does not instruct writes or deletions outside the working project.
Secrets & credentials	2 (moderate)	`SKILL.md` explicitly suggests inspecting credential-related state with `security list-keychains` and `security find-identity -v`, and the tracing examples also print environment values like `IDENTITY`.
Privilege & persistence	0 (none)	There is no sudo, global install, service registration, shell-profile editing, or OS-setting change in the shipped files.
Instruction hijack surface	1 (low)	The bundled pressure-test docs use manipulative prompt-like language such as `"You must choose and act. Don't ask hypothetical questions"`, which is pressure/injection style text even though it is in test material.
Irreversible actions	0 (none)	The skill does not send messages, publish, deploy, pay, or make external decisions on the user's behalf.
Transparency	0 (none)	All shipped files are plain text; there are no binaries, obfuscated blobs, or runtime-downloaded code.

Before installing

Read `find-polluter.sh` first if you plan to use it; it runs `npm test` for each matching file.
Check `SKILL.md` for any commands that touch keychains or identity stores before using it on a machine with real credentials.
Treat `test-pressure-*.md` as test fixtures only; don't feed them into an active agent context unless you want the pressure-test prompts included.

Rated 2026-10-20 by an automated review of 11 files from the skill's repository.

Source

Repository: obra/superpowers (all skills from this repository)
Path: skills/systematic-debugging/SKILL.md
Branch: main
Updated: 2026-09-19

debugging-and-error-recovery — Guides systematic root-cause debugging.
observability-and-instrumentation — Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting.
performance-optimization — Optimizes application performance across frontend, backend, queries, and databases.
security-and-hardening — Hardens code against vulnerabilities.
diagnosing-superpowers — Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results.
executing-plans — Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution.