Systematic Debugging

Enforces a four-phase workflow for root-cause analysis of software issues before fixes are allowed.

Updated Sep 16, 2023
One-click install
npx skills add https://github.com/paopp2/dotfiles --skill systematic-debugging-paopp2
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Systematic Debugging
Source: https://github.com/paopp2/dotfiles/tree/main/.claude/skills/debugging/systematic-debugging
Command: npx skills add https://github.com/paopp2/dotfiles --skill systematic-debugging-paopp2

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? This skill eliminates the time-wasting cycle of random fixes and symptom-patching, ensuring you find and resolve the true root cause of any technical issue.

Core Features & Use Cases:

  • Four-Phase Framework: Guides you through Root Cause Investigation, Pattern Analysis, Hypothesis & Testing, and Implementation for thorough problem-solving.
  • Root Cause Mandate: Enforces finding the true origin of a bug before attempting any fixes, preventing symptom-whack-a-mole.
  • Pressure-Resistant Rules: Includes explicit anti-patterns and "red flags" to prevent shortcuts, even under tight deadlines or social pressure.

Quick Start: I've encountered a bug. Use the Systematic Debugging skill to guide me through Phase 1: Root Cause Investigation.

Frequently Asked Questions about Systematic Debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find the root cause of a bug instead of just applying quick fixes?

Root cause analysis requires a systematic four-phase workflow: investigate the failure, analyze patterns, test hypotheses, then implement the fix. This approach prevents symptom-patching by enforcing evidence-based diagnosis before any code changes, saving time on recurring issues.

What's the best way to debug production incidents under pressure?

Systematic debugging includes pressure-resistant rules and explicit anti-patterns that prevent shortcuts even under tight deadlines. Following the four-phase framework—investigation, pattern analysis, hypothesis testing, and implementation—ensures thorough root-cause resolution rather than temporary patches.

Can I use this debugging methodology for test failures and performance problems?

Yes. The four-phase workflow applies across all software issues: bugs, test failures, production incidents, and performance problems. Each phase enforces exhaustive root-cause analysis with mandatory failure-mode documentation before implementation.

Why does my bug keep reappearing after I fix it?

Recurring bugs signal symptom-based patching rather than root-cause fixes. Systematic debugging mandates Phase 1 investigation and Phase 2 pattern analysis to identify the true origin, preventing the cycle of random fixes and ensuring lasting resolution.

What should I do during Phase 1 root cause investigation?

Phase 1 focuses on gathering evidence: reproduce the issue, isolate failure conditions, and map system state at failure time. Document what you observe before forming hypotheses, establishing the factual foundation required before moving to pattern analysis and testing.

How do I know when I've found the actual root cause?

Root cause is confirmed when you have testable evidence linking a specific condition to the failure. Phase 3 hypothesis testing validates this connection; a fix addressing the true root cause prevents recurrence, whereas symptom-based patches fail repeatedly.