systematic-debugging

Guide engineers through a four-phase root-cause debugging workflow.

Updated Feb 6, 2026
One-click install
npx skills add https://github.com/chadananda/xswarm-tdd-claude --skill systematic-debugging-chadananda
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/chadananda/xswarm-tdd-claude/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/chadananda/xswarm-tdd-claude --skill systematic-debugging-chadananda

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a disciplined, phase-driven approach to debugging. It helps teams avoid patchwork fixes by ensuring root-cause investigation happens before proposing any changes, reducing rework and introducing fewer new bugs.

Core Features & Use Cases

  • Four-Phase Method: Phase 1: Root Cause Investigation, Phase 2: Pattern Analysis, Phase 3: Hypothesis & Testing, Phase 4: Implementation.
  • Evidence-Driven Debugging: Read error messages, reproduce reliably, trace data flow, and collect diagnostic data.
  • Broad Applicability: Useful for test failures, production incidents, build failures, and integration issues across software projects.
  • Safety & Quality: Emphasizes minimal, verifiable changes and validation before claiming resolution.

Quick Start

Start by reproducing the issue, capturing exact errors, and listing what changed recently. Then map data flow, identify root cause, form a single failure hypothesis, test it with minimal changes, and implement a validated fix with tests.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
What is root-cause debugging and how does it prevent recurring software bugs?

Root-cause debugging is a phase-driven workflow that replaces symptom fixes with validated fixes. By enforcing evidence gathering, pattern analysis, and hypothesis testing before implementation, it ensures safe resolutions and prevents patchwork fixes from introducing new bugs.

How do I debug production incidents using a systematic root-cause workflow?

Debug production incidents by first reproducing the issue reliably and capturing exact error messages. Then trace data flow to collect diagnostic evidence, map patterns to form a single failure hypothesis, test it with minimal changes, and implement a validated fix.

Can I use a phase-based debugging method for build failures and test issues?

Yes, a phase-based debugging method applies broadly to test failures, build failures, production incidents, and integration issues. It guides you through evidence collection and pattern analysis across software projects to resolve any unexpected behavior safely.

What is the best way to stop applying patchwork fixes to recurring failures?

The best way to stop patchwork fixes is adopting a defense-in-depth approach that enforces root-cause investigation before proposing changes. By validating a single failure hypothesis with minimal, verifiable changes, you ensure reliable resolutions and reduce rework.

Why should I gather diagnostic evidence before changing code to fix an error?

Gathering diagnostic evidence before changing code ensures you trace data flow accurately and identify the actual failure pattern. This evidence-driven debugging approach prevents premature symptom fixes, reducing the risk of introducing fewer new bugs during implementation.

When should I avoid systematic debugging and just patch the symptom?

Systematic debugging should never be avoided for unexpected behavior, as patching symptoms without root-cause analysis introduces rework and new bugs. Even for minor failures, enforcing evidence collection and hypothesis testing ensures safe, verifiable resolutions.