What does this skill do, and when should you use it?
Systematic Debugging is a four-phase workflow for technical failures and unexpected behavior. It starts with careful error reading, reliable reproduction, recent-change review, evidence gathering, and data-flow tracing. It then analyzes working patterns, formulates one hypothesis, and tests it with the smallest possible change. After the root cause is established, it requires a failing test, one focused fix, and verification; three or more failed fixes trigger an architecture discussion.
The skill directs an agent to read complete errors and stack traces, record exact reproduction steps, inspect Git diffs and recent commits, and add diagnostic logging at component boundaries in multi-layer systems. It then asks the agent to find working examples, compare every relevant difference, state one specific root-cause hypothesis, and test it one variable at a time. Once the cause is understood, it requires a minimal failing test, a single root-cause fix, and verification that the issue is resolved without breaking other tests. It may also direct the agent to read root-cause-tracing.md, defense-in-depth.md, and condition-based-waiting.md in the same directory.
- A developer has a recurring test failure and needs to separate code, configuration, and environment causes.
- An engineer is diagnosing a production incident across workflow, build, service, and database boundaries.
- A team is investigating a build or integration failure and needs a disciplined comparison with a working path.
- A developer has tried several fixes and needs to decide whether the underlying architecture is the real problem.
- An engineer under deadline pressure needs to avoid speculative patches that create further rework.
How do you install this skill?
- Diagnostic examples may expose environment variables, signing identities, directories, stack traces, or other sensitive runtime information; define redaction, access control, and retention before use.
- The universal trigger and absolute no-fix-before-root-cause rule may conflict with production emergencies, irreproducible failures, or immediate safety mitigations; explicit escalation, containment, and rollback conditions are needed.
- The creation log and impact metrics lack reproducible test artifacts and should not be treated as independently validated.
- Shell / CLI
- Local filesystem
Git
The repository is a collection of 14 skills, and the README does not document a standalone installation command for systematic-debugging. Install the Superpowers collection through the target coding agent's documented method; the README states that installation is separate for each harness. The repository is licensed under MIT.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/obra/superpowers.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/systematic-debugging" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- I have a failing integration test. Follow systematic-debugging Phase 1 first and do not propose fixes yet.
Use it whenever a bug, test failure, or unexpected behavior appears. Example trigger: "I have a failing integration test. Follow systematic-debugging Phase 1 first and do not propose fixes yet." Do not propose a fix until the root-cause investigation is complete.
What are this skill's strengths and limitations?
- Covers test failures, production bugs, performance problems, build failures, and integration issues.
- Provides explicit steps for reproduction, evidence collection, data-flow tracing, and hypothesis testing.
- Includes failing-test creation, focused implementation, and regression verification.
- Escalates repeated failure after three or more fixes into an architecture discussion.
- Requires completing each phase before proceeding, even when the issue appears simple.
- Requires filesystem access and shell execution; no particular test framework is specified.
- The stated 15–30 minute fix time and 95% first-time fix rate are not supported by a documented evaluation method in the supplied material.
- The referenced supporting files and related skills are not included in the supplied material.
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Systematic Debugging this page | 48 · Use with care | ★ 299k | 15d ago | MIT |
| NeMo-RL Auto Research ✓ NVIDIA · Official | 51 · Use with care | ★ 3.6k | 11d ago | Apache-2.0 |
| ce-debug: Systematic Bug Diagnosis & Fix | 55 · Use with care | ★ 26k | 11d ago | MIT |
| Parallel Agent Dispatch | 50 · Use with care | ★ 299k | 15d ago | MIT |
| MAIC Importer Development Skill | 52 · Use with care | ★ 41k | 11d ago | MIT |
Compared with random fix-and-guess debugging, it establishes an evidence chain, identifies the root cause, and then applies and verifies a minimal change.
How did FollowSkills review this skill?
The skill emphasizes investigation before changes, data-flow tracing, layered validation, and human discussion after repeated failure, which reduces reckless modification risk. However, its examples instruct agents to log environment-variable availability, signing identities, keychain state, and stack traces without guidance on redaction, least privilege, confirmation, rollback, or retention, so points are deducted.
The four-phase process, timeout messages, and abnormal-case guidance are coherent, and the referenced support files are present in the supplied material. However, the shell script assumes Unix tools, npm, and project-specific test behavior; path spaces, argument edge cases, isolation, and polling semantics are not fully handled. Static review cannot prove key-path execution, so the score remains below 10.
Triggers, scenarios, anti-patterns, and the non-fit case of genuine timing tests are clearly described for common software debugging. However, the trigger 'any technical issue' is broad, boundaries for emergencies, irreproducible issues, and non-code failures are incomplete, and there is no evidence of Chinese-language or mainland-China environment adaptation, so points are deducted.
The material has clear phases, a quick reference, supporting techniques, examples, a shell utility, repository-level MIT licensing, and package version metadata. The selected skill lacks standalone installation/dependency notes, versioning policy, changelog, maintenance ownership, and update path; creation-log test and impact claims are not independently verifiable, so points are deducted.
The skill supplies an actionable root-cause investigation, hypothesis-testing, and verification checklist that could reduce guess-and-check work. However, static material does not verify representative outputs or actual results, and requiring the full process can impose cost during simple or urgent incidents; effectiveness claims still require substantial human review, so points are deducted.
The supplied files mutually support the process and its auxiliary techniques, and the creation log describes a test design. There are no verifiable test-run records, CI coverage of this skill's key paths, or third-party reproduction evidence; quantitative claims such as 95% first-time fixes and 60%-to-100% pass-rate improvement are author assertions, so only limited credit is justified.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →