systematic-debugging

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Developers under time pressure often apply quick symptom fixes that fail repeatedly, causing hours of guess-and-check thrashing. 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: Root cause investigation, pattern analysis, hypothesis testing, and verified implementation with explicit gates between phases. - 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: Red flags, rationalization tables, and anti-pattern lists that catch shortcut behavior during emergencies, plus a rule to question the architecture after three failed fixes. - Use Case: When a production test fails intermittently, follow Phase 1 to reproduce and gather evidence, trace the bad value to its source, then fix at the origin and add validation at every layer the data passes through. ## Quick Start Use the systematic-debugging skill to investigate this failing test and find its root cause before suggesting 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 find the root cause of a bug instead of fixing symptoms?▼

Follow the four-phase process: read error messages fully, reproduce the issue consistently, check recent changes, and trace the bad value backward through the call stack to its origin. Only form a single hypothesis and test it minimally before implementing any fix.

How to fix flaky tests caused by arbitrary timeouts?▼

Replace setTimeout or sleep calls with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. The included TypeScript helpers waitForEvent, waitForEventCount, and waitForEventMatch poll every 10ms with a configurable timeout.

What should I do when my first debugging fix doesn't work?▼

Stop and return to Phase 1 to re-analyze with the new information rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss the fundamental design with your team before attempting another fix.

How do I find which test is polluting shared state or creating files?▼

Use the included find-polluter.sh bisection script with the polluted path and a test file pattern. It runs each test file individually and stops at the first one that creates the unwanted file or directory, identifying the exact polluter.

When is it acceptable to skip systematic debugging for simple bugs?▼

According to the skill, never. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation under time pressure leads to symptom fixes that guarantee rework and repeated failures.