systematic-debugging
Systematic Debugging enforces a disciplined four-phase process: investigate root cause, analyze patterns, form and test hypotheses, then implement fixes. It stops you from guessing at solutions and catching yourself in cycles of failed patches that mask underlying problems.
Systematic Debugging helps you find the actual root cause of a bug before attempting any fix.
AI-generated summary based on this skill's SKILL.md
Install
PracticalSwan/agent-skills/systematic-debugging · repository language: Python
git clone https://github.com/PracticalSwan/agent-skills
cp -r agent-skills/systematic-debugging ~/.claude/skills/systematic-debuggingnpx skillfed install PracticalSwan/agent-skills/systematic-debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to debug a problem systematically?
Systematic Debugging guides you through a four-phase process: first investigate to find the root cause rather than treating symptoms, then analyze patterns in failures, form testable hypotheses about what's broken, and only then implement fixes. This disciplined approach stops you from guessing at solutions and prevents cycles of failed patches that mask underlying problems.
What is the root cause analysis for bugs in Systematic Debugging?
Systematic Debugging's root cause analysis phase focuses on understanding why a failure occurred, not just where it appears. By investigating before attempting fixes, you avoid wasting time on wrong solutions. The skill teaches you to trace data flow through multi-component systems and recognize whether you're facing an architectural problem or just a symptom that needs deeper investigation.
How does Systematic Debugging help with production bug investigation?
Systematic Debugging provides a structured framework for investigating production issues and test failures step by step. Rather than jumping to solutions under time pressure, the skill enforces a methodology that has you investigate systematically, analyze patterns, form hypotheses, and test them before implementing fixes. This prevents architectural problems from being masked by temporary patches.
When should I recognize architectural problems vs. symptom fixes?
Systematic Debugging teaches you to distinguish between fixing surface symptoms and addressing underlying architectural issues. During the investigation and pattern-analysis phases, the skill helps you trace bugs through multi-layer systems to see whether repeated failures point to a deeper design problem rather than isolated bugs. This recognition prevents you from applying band-aid fixes that fail repeatedly.
Why does Systematic Debugging emphasize finding root cause before fixing?
Systematic Debugging stops you from guessing at solutions, which creates cycles of failed patches. By enforcing a four-phase process that prioritizes root cause investigation, you avoid wasting time on wrong fixes. The skill ensures you understand the actual failure before implementing solutions, making your debugging more efficient and preventing architectural problems from being masked by temporary workarounds.
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 causes too) - You're in a hurry (rushing guarantees rework) -
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 12 files
systematic-debugging/CHANGELOG.md
systematic-debugging/CREATION-LOG.md
systematic-debugging/SKILL.md
systematic-debugging/condition-based-waiting-example.ts
systematic-debugging/condition-based-waiting.md
systematic-debugging/defense-in-depth.md
systematic-debugging/find-polluter.sh
systematic-debugging/root-cause-tracing.md
systematic-debugging/test-academic.md
systematic-debugging/test-pressure-1.md
systematic-debugging/test-pressure-2.md
systematic-debugging/test-pressure-3.md