systematic-debugging

Diagnose software bugs through a four-phase root-cause investigation framework.

Updated Aug 23, 2026

Search Tags:#testing #debugging #concurrency #phases #root-cause #pattern-analysis #hypothesis-testing

Ready to run

npx skills add https://github.com/HTRamsey/claude-config --skill systematic-debugging-htramsey

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/HTRamsey/claude-config/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/HTRamsey/claude-config --skill systematic-debugging-htramsey

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

When bugs appear, this Skill prescribes a disciplined four-phase workflow that treats symptoms as clues and never flat-out guesses the fix.

Core Features & Use Cases

Phase 1: Root Cause Investigation: Reproduce, inspect errors, and trace data flow to locate the true cause.
Phase 2: Pattern Analysis: Compare against known-good behavior and references to identify differences.
Phase 3: Hypothesis and Testing: Form a single, testable hypothesis and validate with minimal changes.
Phase 4: Implementation: Implement the fix with targeted changes and add regression tests.

Quick Start

Start with Phase 1: Reproduce the bug, collect exact error messages, and confirm the failure scenario before proposing any changes.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema

How do I debug software bugs systematically instead of guessing at fixes?▼

Systematic debugging applies a four-phase framework: root-cause investigation to reproduce and trace the bug, pattern analysis to compare against known-good behavior, hypothesis testing with minimal changes, and targeted implementation with regression tests. This ensures fixes address the underlying cause, not symptoms.

How do I find the root cause of race conditions and concurrency bugs?▼

Root-cause investigation traces data flow and collects exact error messages to locate where the bug originates in multi-component systems. For concurrency issues like race conditions and deadlocks, this phase isolates the timing or synchronization failure before any fix is attempted.

What's the best way to approach test failures and unexpected behavior?▼

Start with Phase 1: reproduce the failure exactly, inspect error messages, and confirm the failure scenario. Pattern analysis then compares the failure against known-good references to identify what changed, forming the basis for a single testable hypothesis before implementation.

Do I need instrumentation and logging to debug effectively?▼

Yes. Evidence collection through instrumentation and logging guidelines ensures you gather concrete data about system state and behavior. This supports root-cause investigation and hypothesis testing while minimizing guesswork and unnecessary code changes.

How do I know when to escalate a bug or change my debugging approach?▼

The framework includes escalation rules that trigger when initial hypotheses fail or when bugs span multiple systems. These rules guide you to re-examine assumptions and adjust your investigation strategy rather than implementing speculative fixes.