systematic-debugging

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Random fixes and quick patches waste time, mask underlying issues, and introduce new bugs. This Skill enforces a disciplined debugging methodology that finds the actual root cause before any fix is attempted, even under time pressure or social pressure to apply a quick patch. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and implementation, with mandatory completion of each phase before proceeding. - Supporting Techniques: Includes root-cause tracing 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 stop shortcut fixes during emergencies, plus a rule to question the architecture after three failed fixes. - Use Case: When a test fails intermittently or production throws an error, load this Skill to systematically reproduce the issue, gather evidence across component boundaries, form a single hypothesis, and verify the fix with a failing test case. ## Quick Start Ask the AI to debug your failing test or bug using the systematic-debugging skill and require it to complete 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 failing test systematically instead of guessing?▼

Follow the four phases: investigate the root cause by reading errors and reproducing consistently, analyze patterns against working examples, form and test a single hypothesis, then implement one fix verified by a failing test case. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by setTimeout and arbitrary delays?▼

Replace arbitrary timeouts with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. Poll every 10ms with a clear timeout error, and only use fixed delays when testing documented timing behavior.

What should I do when a bug appears deep in the call stack?▼

Trace backward through the call chain to find the original trigger rather than fixing where the error appears. Add stack trace instrumentation with console.error before the failing operation, then fix at the source and add validation at each layer the data passes through.

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, so discuss fundamentals with your team before attempting more fixes.

Is it acceptable to skip root cause investigation during a production emergency?▼

No. The skill states systematic debugging is faster than guess-and-check thrashing even under time pressure. Quick symptom fixes set a bad pattern, mask the real issue, and typically cause rework and new bugs.