systematic-debugging

Diagnose bugs through a four-phase root cause investigation process before proposing fixes.

2|Updated Jul 11, 2026
One-click install
npx skills add https://github.com/MoofonLi/dev-ready --skill systematic-debugging-moofonli
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/MoofonLi/dev-ready/tree/main/src/dev_ready/templates/claude/skills/systematic-debugging
Command: npx skills add https://github.com/MoofonLi/dev-ready --skill systematic-debugging-moofonli

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When facing bugs, test failures, or unexpected behavior, developers often jump to quick symptom fixes that mask the real issue and cause recurring problems. This Skill enforces a disciplined four-phase debugging methodology that finds the actual root cause before any fix is attempted. ## Core Features & Use Cases - Four-Phase Process: Structured workflow covering Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation, with mandatory completion of each phase before proceeding. - Supporting Techniques: Includes root-cause-tracing for following bugs backward through call stacks, defense-in-depth validation at multiple layers, and condition-based waiting to replace flaky arbitrary timeouts in tests. - Pressure Resistance: Explicit anti-patterns, red flags, and rationalization tables that prevent shortcut fixes under time pressure, plus a rule to question the architecture after three failed fix attempts. - Use Case: A test fails intermittently in CI. Instead of adding longer sleep delays, you trace the data flow backward, find the empty variable causing the failure, fix it at the source, and add validation at each layer so the bug cannot recur. ## Quick Start Ask the AI to debug a failing test or bug using the systematic-debugging process, starting with root cause investigation before proposing any fix.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I debug a test failure systematically instead of guessing?

Follow the four-phase process: first investigate the root cause by reading errors fully, reproducing the issue, and checking recent changes; then analyze patterns against working examples; form a single hypothesis and test it minimally; finally implement one fix with a failing test case to verify it.

How to find the root cause of a bug deep in the call stack?

Use root cause tracing: identify the immediate failing code, then trace backward through each caller asking what value was passed and where it originated. Add stack trace instrumentation with console.error before the failing operation if manual tracing is not possible.

How do I fix flaky tests caused by timing issues?

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual condition you need, such as an event appearing or state changing. The skill includes a waitFor polling pattern and example helpers like waitForEvent and waitForEventCount.

When should I stop trying fixes and question the architecture?

Stop after three failed fix attempts. If each fix reveals a new problem in a different place or requires massive refactoring, the pattern indicates an architectural problem, and you should discuss fundamentals with your team before attempting more fixes.

What is defense-in-depth validation after fixing a bug?

It means adding validation at every layer data passes through: entry point checks, business logic validation, environment guards, and debug instrumentation. This makes the bug structurally impossible rather than relying on a single check that other code paths can bypass.