systematic-debugging
Systematic Debugging enforces a disciplined four-phase approach to troubleshooting: investigate the root cause through error analysis and evidence gathering, analyze patterns by comparing working and broken code, form and test hypotheses scientifically, then implement fixes. The skill emphasizes that symptom-level repairs fail—you must trace data flow, instrument multi-component systems, and stop after three failed attempts to question architectural soundness.
Systematic Debugging guides you through a four-phase process to identify root causes before proposing any fixes.
AI-generated summary based on this skill's SKILL.md
Install
obra/superpowers/systematic-debugging · repository language: Shell
git clone https://github.com/obra/superpowers
cp -r superpowers/skills/systematic-debugging ~/.claude/skills/systematic-debuggingnpx skillfed install obra/superpowers/systematic-debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I find the root cause of a bug before fixing it?
Systematic Debugging guides you through a four-phase approach: first investigate by gathering error messages and evidence, then analyze patterns by comparing working versus broken code paths. Form a hypothesis about what's wrong, test it with minimal instrumentation, and only after confirming the root cause implement your fix. This prevents symptom-level repairs that mask deeper issues.
What is the systematic approach to troubleshooting production issues?
Systematic Debugging emphasizes tracing data flow through your multi-component system to locate where failures occur. Instrument each layer to see what's actually happening rather than guessing. If three different fixes fail, stop and question whether an architectural problem exists instead of continuing to patch symptoms.
How do I debug test failures systematically?
Systematic Debugging teaches you to investigate the root cause through error analysis and evidence gathering before attempting any fixes. Compare the failing test's behavior against passing tests to identify patterns. Form a hypothesis about the difference, verify it with targeted testing, then implement your fix only after confirming the actual root cause.
How can I trace bugs in code using a structured debugging approach?
Systematic Debugging applies the scientific method to debugging: gather evidence from logs and errors, analyze patterns by examining working and broken code side-by-side, form testable hypotheses, and verify them with minimal instrumentation before fixing. This structured workflow prevents wasted time on incorrect assumptions and surface-level repairs.
What should I do when multiple debugging attempts fail?
Systematic Debugging recommends stopping after three failed fix attempts to reassess. Rather than continuing to patch symptoms, question whether an architectural problem exists. Trace data flow across components to see if the issue lies in system design rather than isolated code. This prevents endless cycles of ineffective fixes.
How does Systematic Debugging help with debugging under time pressure?
Systematic Debugging's disciplined four-phase process—investigate, analyze, hypothesize, test—actually saves time by eliminating guesswork. By finding the root cause first rather than trying random fixes, you avoid wasted effort. The framework also tells you when to stop patching and escalate to architectural review, preventing prolonged firefighting.
SKILL.md
rendered from the published skill — quoted content, verbatim
Systematic Debugging
Overview
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
When to Use
Use for ANY technical issue: - Test failures - Bugs in production - Unexpected behavior - Performance problems - Build failures - Integration issues
Use this ESPECIALLY when: - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious - You've already tried multiple fixes - Previous fix didn't work - You don't fully understand the issue
Don't skip when: - Issue seems simple (simple bugs have root causes too) - You're in a hurry (rushing guarantees rework) - Manager wants it fixed NOW (systematic is faster than thrashing)
The Four Phases
You MUST complete each phase before proceeding to the next.
Phase 1: Root Cause
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 11 files
skills/systematic-debugging/CREATION-LOG.md
skills/systematic-debugging/SKILL.md
skills/systematic-debugging/condition-based-waiting-example.ts
skills/systematic-debugging/condition-based-waiting.md
skills/systematic-debugging/defense-in-depth.md
skills/systematic-debugging/find-polluter.sh
skills/systematic-debugging/root-cause-tracing.md
skills/systematic-debugging/test-academic.md
skills/systematic-debugging/test-pressure-1.md
skills/systematic-debugging/test-pressure-2.md
skills/systematic-debugging/test-pressure-3.md