This skill, authored by the original creator of superpowers, is triggered when encountering test failures, production incidents, build failures, or any abnormal behavior. Its core rule is: "No fix proposals without a root cause investigation." Phase one involves reading the full error message, achieving stable reproduction, and checking recent changes; for multi-component systems, add logging at each boundary to identify which layer is failing. Phase two involves finding similar code that works correctly and comparing it item by item. Phase three involves validating only one hypothesis at a time. Only then do you apply the fix. The more rushed you feel, or the more you think "just changing one line will do," the more strictly you must follow the entire process.
Why it matters A common flaw in how agents fix bugs is changing code immediately upon seeing symptoms, then layering on more changes when the first attempt fails. This skill divides the process into four mandatory sequential phases: investigation, comparison, hypothesis validation, and fixing.
skills.sh install count 333427 (+1239 / 24h)
Security Audit: Risk warnings present
- Instructs the agent to execute shell / script commands
- Audit scope: GitHub obra/superpowers/skills/systematic-debugging/SKILL.md (only the SKILL.md text was scanned)
Rationale
- skills.sh installs 1239 in 24 hours, with a cumulative total of 333427 (indicating only attention level); MIT license
- The commands flagged in the audit prompt (git diff and adding logs for troubleshooting) are used during the investigation phase and align with the skill's purpose; this is the original obra repository, not a cloned account
Usage
- Once installed, the agent will automatically follow the four-phase troubleshooting process when encountering errors or test failures; you can also explicitly say, "Don't fix it yet, find the root cause of this problem."
Risks
- During troubleshooting, diagnostic logs are temporarily added to the code and commands are executed; ensure these changes are cleaned up afterward.