systematic-debugging
Systematic Debugging enforces disciplined root-cause investigation before any code changes, using a 4-phase pipeline: evidence gathering, pattern comparison, hypothesis testing, and targeted fixes. It prevents the common failure mode of applying surface-level patches that mask underlying issues. Works with test failures, production bugs, performance problems, and build failures across any tech stack.
Systematic Debugging diagnoses the root cause of bugs and errors through a structured 4-phase investigation before any fix is applied.
AI-generated summary based on this skill's SKILL.md
Install
FradSer/dotclaude/systematic-debugging · repository language: JavaScript
git clone https://github.com/FradSer/dotclaude
cp -r dotclaude/superpowers/skills/systematic-debugging ~/.claude/skills/systematic-debuggingnpx skillfed install FradSer/dotclaude/systematic-debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to debug a bug systematically with Systematic Debugging?
Systematic Debugging enforces a 4-phase pipeline: evidence gathering (collect logs, stack traces, reproduction steps), pattern comparison (identify what changed), hypothesis testing (isolate the actual cause), and targeted fixes (apply only after root cause is confirmed). This prevents surface-level patches that mask underlying issues and works across test failures, production bugs, performance problems, and build failures on any tech stack.
What's the root cause analysis process for test failures?
Systematic Debugging treats test failures by first gathering evidence—the exact failure output, preceding test state, and reproduction conditions. Then compare patterns: did this test pass before, and what changed? Form hypotheses about the actual cause rather than the symptom. Only after confirming the root cause does Systematic Debugging guide you to write a regression test and apply the fix, ensuring the bug won't resurface.
How do I find where bad data originates in a multi-component system?
Systematic Debugging traces data flow by mapping each layer's input and output during evidence gathering. Compare patterns across components to pinpoint where corruption begins. Test hypotheses by instrumenting checkpoints between layers. This structured approach isolates whether bad data comes from an upstream service, a transformation step, or a database query—not just where it's observed.
When should I question architecture if multiple fixes fail independently?
Systematic Debugging raises architectural concerns when the evidence-gathering and pattern-comparison phases reveal that independent fixes all fail. This signals the root cause isn't in individual components but in how they interact. Before applying more patches, hypothesis testing should examine the overall design: message ordering, state consistency, or coupling assumptions that no single fix can address.
How does Systematic Debugging help debug CI build failures?
Systematic Debugging applies its 4-phase pipeline to CI failures: gather full build logs and environment state, compare against passing builds to spot differences, form hypotheses about whether the issue is flaky infrastructure, dependency changes, or code logic, then verify the root cause before fixing. This prevents chase-the-symptom cycles and creates regression tests to catch the failure again.
What makes Systematic Debugging different from just fixing the symptom?
Systematic Debugging enforces root-cause investigation before any code changes, preventing the common failure of applying patches that hide deeper issues. By following evidence gathering, pattern comparison, and hypothesis testing, you discover why code behaves unexpectedly rather than where it breaks. This discipline works across any tech stack and ensures fixes are durable, not temporary masks.
SKILL.md
rendered from the published skill — quoted content, verbatim
Systematic Debugging
Slash-command Usage
Invoked via /superpowers:systematic-debugging "<symptom>" or auto-loaded by other skills when bug-fix language is detected.
When invoked as a slash command: capture $ARGUMENTS as the symptom statement and start at Phase 1 immediately. Do NOT write design documents or task files; the deliverable is the fix + a test that catches the regression, not a docs/plans/ folder.
Output discipline: Report findings inline as
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 7 files
superpowers/skills/systematic-debugging/SKILL.md
superpowers/skills/systematic-debugging/find-polluter.sh
superpowers/skills/systematic-debugging/references/condition-based-waiting-example.ts
superpowers/skills/systematic-debugging/references/condition-based-waiting.md
superpowers/skills/systematic-debugging/references/defense-in-depth.md
superpowers/skills/systematic-debugging/references/rationalizations-and-guardrails.md
superpowers/skills/systematic-debugging/references/root-cause-tracing.md