systematic-debugging
This skill enforces a disciplined debugging methodology that prioritizes root cause discovery over quick patches. Work through four phases—investigation, pattern analysis, hypothesis testing, and implementation—completing each before advancing. The framework prevents the trap of symptom-fixing by requiring evidence gathering across component boundaries and data flow tracing before any fix attempt.
Systematic Debugging guides you through a four-phase framework to identify root causes before proposing any fixes.
AI-generated summary based on this skill's SKILL.md
Install
secondsky/claude-skills/systematic-debugging · repository language: TypeScript
git clone https://github.com/secondsky/claude-skills
cp -r claude-skills/plugins/systematic-debugging/skills/systematic-debugging ~/.claude/skills/systematic-debuggingnpx skillfed install secondsky/claude-skills/systematic-debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What is systematic-debugging and why does it matter?
systematic-debugging is a skill that enforces a disciplined methodology prioritizing root cause discovery over quick patches. Rather than applying fixes to visible symptoms, it guides you through four structured phases—investigation, pattern analysis, hypothesis testing, and implementation—ensuring each phase completes before advancing. This prevents the costly trap of symptom-fixing and reduces failed fix attempts.
How do I find root cause not just symptoms when debugging?
systematic-debugging requires evidence gathering across component boundaries and data flow tracing before any fix attempt. Start by investigating what actually failed, then analyze patterns to distinguish root causes from symptoms. Trace data flow through your multi-component system to locate where failures originate, not where they surface. Only after identifying the true cause should you test and implement a fix.
What is the four-phase debugging framework this skill teaches?
systematic-debugging structures debugging into four sequential phases: investigation (gather facts about the failure), pattern analysis (identify what's actually broken), hypothesis testing (validate your theory before coding), and implementation (apply the fix). Complete each phase fully before moving to the next. This prevents jumping to solutions prematurely and ensures you're fixing root causes, not chasing symptoms.
Why did my fix not work and how do I investigate?
systematic-debugging addresses repeated fix failures by requiring you to trace data flow through multi-component systems and verify you've identified the actual root cause. When multiple fixes fail, the framework guides you to step back and re-examine whether you're fixing symptoms rather than causes. It also helps determine if an architectural refactor is needed versus continued targeted fixing.
How do I debug production bugs step by step systematically?
systematic-debugging applies to production bugs by enforcing a methodical approach: investigate the failure conditions, analyze patterns across logs and components, form and test hypotheses about root cause, then implement fixes. This structured process works under time pressure by preventing wasted effort on symptom-fixes and ensuring you understand data flow before deploying changes.
When should I stop trying fixes and consider refactoring instead?
systematic-debugging helps you determine if an architectural refactor is needed versus continued fixing by completing the four-phase process fully. If investigation and pattern analysis reveal systemic design issues rather than isolated bugs, or if multiple fix attempts fail despite proper root cause analysis, the framework signals that refactoring may be more efficient than continued patching.
SKILL.md
rendered from the published skill — quoted content, verbatim
Systematic Debugging
Overview
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
plugins/systematic-debugging/skills/systematic-debugging/SKILL.md