systematic-debugging

Guide engineers through a four-phase systematic debugging process to identify root causes.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Four-phase systematic debugging ensures root-cause investigation is completed before attempting fixes, resisting time pressure and rationalization.

Core Features & Use Cases

  • Phase-driven workflow: Phase 1 Root Cause Investigation, Phase 2 Pattern Analysis, Phase 3 Hypothesis & Testing, Phase 4 Implementation, with explicit stop rules and anti-patterns.
  • Evidence-based debugging: Reproduce, gather diagnostics, compare against references, and verify root cause before changes.
  • Safety & integration: Encourages documentation of findings and integration with related skills (root-cause tracing, validation, testing).

Quick Start

Load the skill at skills/debugging/systematic-debugging, read the overview, then follow Phase 1 checklist before proposing fixes. If you are tempted to skip, consult the anti-patterns and pause. Complete all four phases to resolve the issue.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I identify the root cause of a bug before attempting a fix?▼

Systematic debugging prevents skipped investigation by enforcing a four-phase workflow: root cause investigation, pattern analysis, hypothesis testing, and implementation. It resists time pressure by mandating evidence gathering before any fixes are applied.

What is the best way to debug complex system failures systematically?▼

Systematically debugging complex system failures requires completing four explicit phases with stop rules. You gather diagnostics, compare against references, and establish a reproducible root cause before implementation, escalating if the root cause remains unidentified.

How do I structure a debugging workflow to avoid jumping to conclusions?▼

A structured debugging workflow avoids premature conclusions by enforcing strict no fixes without root cause mandates. It uses anti-patterns to resist rationalization and time pressure, requiring evidence gathering and hypothesis testing before implementation.

Why do my bug fixes introduce new issues instead of solving the original problem?▼

Bug fixes introduce new issues when applied without identifying the root cause. Systematic debugging prevents this by enforcing evidence gathering, pattern analysis, and hypothesis testing across four phases before any implementation changes are made.

Can I use a four-phase debugging process for simple bugs and complex systems?▼

Yes, the four-phase systematic debugging process covers both simple bugs and complex systems. It scales by applying explicit Phase 1 to 4 steps, anti-patterns, and documentation requirements to any issue, escalating only if no root cause is found.

When should I escalate a bug that I cannot find the root cause for?▼

You should escalate a bug when the systematic debugging process cannot establish a root cause. The workflow includes explicit stop rules that trigger escalation if evidence gathering, pattern analysis, and hypothesis testing fail to identify the underlying issue.