Systematic Debugging
Requires completing root-cause investigation before proposing any fix — explicitly bans "just try changing this and see"
Provides a clear four-phase root-cause workflow for test failures, production bugs, build failures, performance issues, and integration problems, with a plausible advantage over guess-and-check fixes. The boundaries are partly explicit, but the absolute rule requiring all phases before any fix may be unsuitable for emergency mitigation, known simple faults, or service-restoration scenarios. Its claimed effectiveness is not independently verified.
The process is structured with explicit checkpoints, single-hypothesis testing, minimal changes, re-analysis after failure, and architectural review after three failed fixes. Supporting materials cover root-cause tracing, condition-based waiting, defense in depth, and test-pollution investigation. Evidence gaps remain: cross-language, cross-platform, and cross-framework reproducibility is not shown; the shell script depends on Bash, find, and npm test, and suppresses individual test command failures, which can hide diagnostic failures.
The skill does not itself execute external actions and does not require networking, credential access, or exfiltration, so direct privilege risk is relatively low. However, its examples explicitly log environment-variable availability, keychain identities, and stack/context data without prescribing redaction, minimum logging scope, retention, or deletion. Examples involving git init, test execution, and filesystem inspection also lack explicit consent, isolation, and rollback controls. The absolute prohibition on mitigation before investigation could increase harm during production incidents.
SKILL.md and its supporting files provide traceable steps, examples, and scenario tests. CREATION-LOG.md claims that four validation tests passed and reports real-session outcomes and impact figures. This review is static only, so those tests, environments, samples, versions, and results cannot be confirmed. Claims such as 95% first-time fix rate, 60%-to-100% pass-rate improvement, and 1847 tests passing lack independent corroboration and are not consistently separated from author inference.
Trigger conditions, phase boundaries, anti-patterns, success criteria, and several command examples make the process reasonably actionable. Missing elements include a standardized input/output or investigation-record template, guidance for different languages and toolchains, sensitive-log handling, cost controls, parallel-test effects, permission requirements, and a clear exit or escalation path when a phase cannot be completed. Some related-skill references also assume other skills are available.
The repository supplies an MIT license, package version 6.1.1, a creation log, and general contribution/update guidance, providing limited governance signals. The selected skill has no skill-level version, changelog, named maintainer, compatibility matrix, or explicit update path. The creation-log date of 2025-10-03 does not establish current validity. The publisher is not verified in the FollowSkills enterprise registry, so identity and governance responsibility remain unknown and receive no publisher-based credit.
- Do not copy the examples that log environment variables, keychain identities, or credential availability without redaction, scope limits, and confirmation that logs will not enter shared or persistent systems.
- During production incidents, a human should decide whether to apply a reversible temporary mitigation first; the no-fix-before-root-cause rule should not replace incident-response judgment.
- Before running find-polluter.sh, use an isolated workspace and confirm test side effects, command permissions, and cleanup; the script runs tests one by one and suppresses test-command errors.
- Treat the creation-log test results and impact figures as unverified author claims, not independent quality evidence.
What it does & when to use it
Splits debugging into four phases that must be completed in order — root cause investigation, pattern analysis, hypothesis and testing, implementation — with an iron rule that no fix may be proposed before Phase 1 is done. The doc catalogs real rationalization phrases ("this looks simple," "let me just try changing this first") with counters for each, and includes a rule that three consecutive failed fixes on the same issue means stop and question the architecture, preventing endless patching in the wrong direction.
Phase 1, root cause: read the full error and stack trace, confirm reliable reproduction, check recent changes, and for multi-component systems, add diagnostic logging at every component boundary to locate which layer actually fails. Phase 2, pattern analysis: find a working example elsewhere in the same codebase and list every difference from the broken code. Phase 3, hypothesis and testing: state one specific hypothesis, make the smallest possible change to test it, and form a new hypothesis rather than stacking a second fix on top of a failed one. Phase 4, implementation: write a failing test that reproduces the issue first (pairs with the test-driven-development skill), make exactly one change, and verify it passes without breaking anything else. If the same issue survives three consecutive failed fix attempts, the rule requires stopping to discuss whether the architecture itself is the problem instead of attempting a fourth fix.
- The default first step for any technical issue — failing test, production bug, performance anomaly
- A cross-component problem (e.g. a CI → build → signing pipeline) gets diagnostic logging added at each boundary to locate the failing layer instead of guessing
- The same bug has already survived two failed fixes — the third failure triggers the "stop and question the architecture" rule instead of attempting a fourth patch
Pros & cons
- Bans the most common low-quality debugging pattern — poking at code hoping it fixes itself — with an iron rule plus a rationalization table, not a vague "investigate carefully"
- The "3 failed fixes means question the architecture" rule has real practical value, preventing indefinite time investment in the wrong direction
- Gives concrete calibration like "95% of 'no root cause found' cases are actually incomplete investigation" instead of vague folk wisdom
- Only reliably self-enforcing on harnesses that actually read and follow SKILL.md instructions (Claude Code, Codex CLI, etc.) — in a plain chat interface it's just a document a human has to apply by hand.
- The four-phase process applies even to genuinely trivial bugs (an obvious typo), which can feel like overkill for those cases
- The multi-component diagnostic-logging technique needs an environment that can actually execute commands and read log output — not usable for pure static code review
How to install
Installed as part of the obra/superpowers plugin — individual skills can't be installed standalone:
- Claude Code: official marketplace
/plugin install superpowers@claude-plugins-official; or register the community marketplace with/plugin marketplace add obra/superpowers-marketplacethen/plugin install superpowers@superpowers-marketplace - Also supports Antigravity, Codex App/CLI, Cursor, Factory Droid, GitHub Copilot CLI, Kimi Code, OpenCode, and Pi — see the repo README for the exact command per harness
Once installed, this skill activates alongside the other 13 Superpowers skills, auto-triggered by using-superpowers based on context — there's no separate invocation step.
How to use
Triggers automatically on any bug, test failure, or unexpected behavior — root-cause investigation runs before any fix is proposed. Explicitly reinforced under time pressure or when an issue "looks simple," since the red-flags list specifically calls out those rationalizations.
Compared to similar skills
Compared to not having this skill and letting the model try edits on sight of an error, the four-phase process adds a mandatory root-cause-confirmation step that, per the doc's own account, meaningfully reduces both "fixed it but not really" and introducing new bugs (the doc cites 15-30 minutes for systematic debugging vs. 2-3 hours of thrashing, and a 95% vs. 40% first-fix success rate — that's the author's own reported experience, not a number this site has independently re-verified).