Systematic Debugging
Find the root cause before changing code, reducing trial-and-error rework.
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.
- 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.
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.
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 do you install this skill?
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.
How do you use this skill?
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.
How does this skill compare with similar options?
Compared with random fix-and-guess debugging, it establishes an evidence chain, identifies the root cause, and then applies and verifies a minimal change.