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
Decision gist · record as of 2026-07-24
Systematic Debugging guides you through a four-phase process to identify root causes before proposing any fixes. 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.
Use it when
- Systematic Debugging emphasizes tracing data flow through your multi-component system to locate where failures occur.
- Systematic Debugging teaches you to investigate the root cause through error analysis and evidence gathering before attempting any fixes.
Verify before relying
Read SKILL.md below before installing (11 files). Open directory: indexed for reading, not audited.
Similar skills
Install
obra/superpowers/systematic-debugging · repository language: Shell
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
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
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Find the root cause of a bug or test failure before attempting fixes”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Systematic Debugging teaches a disciplined 4-phase approach: root cause investigation, pattern analysis, hypothesis testing, and implementation. Rather than attempting quick fixes, this skill enforces tracing issues back to their source through careful error analysis, data flow tracking, and minimal testing before any code change.
Diagnostic Analysis guides you through a four-phase debugging methodology that prioritizes root cause investigation over quick fixes. It emphasizes gathering evidence in multi-component systems, comparing working patterns, forming testable hypotheses, and implementing targeted solutions—stopping to question architecture if multiple fixes fail.
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.
This skill walks you through the test-first workflow: write a failing test, verify it fails correctly, implement just enough code to pass, then refactor while keeping tests green. You'll learn why test order matters, how to recognize when you're rationalizing shortcuts, and how to apply TDD to features, bug fixes, and refactoring across any language.
vc-debug guides you through structured investigation before any fix, combining root cause tracing, defense-in-depth validation, and verification protocols. Handle code bugs, system failures, CI/CD issues, and performance degradation with frameworks for each scenario—from call stack analysis to log inspection to frontend verification.
Systematic Debugging enforces a disciplined four-phase approach to troubleshooting: start with root cause investigation, then research external context, analyze patterns, and test hypotheses before implementing any fix. The skill prevents the common trap of patching symptoms, ensuring you understand what actually broke and why.
More skills Systematic Debugging (unlicensed) · systematic-debugging (MIT) · investigate (MIT) · laravel-systematic-debugging (MIT)