systematic-debugging

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

1|Updated Aug 27, 2025
One-click install
npx skills add https://github.com/IgorGanapolsky/Random-Timer --skill systematic-debugging-igorganapolsky
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/IgorGanapolsky/Random-Timer/tree/main/.cursor/skills/systematic-debugging
Command: npx skills add https://github.com/IgorGanapolsky/Random-Timer --skill systematic-debugging-igorganapolsky

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 thrashing and recurring bugs. 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 escalation rules (question the architecture after 3 failed fixes) keep the process intact during emergencies. - Use Case: A test suite has flaky failures from race conditions. Instead of adding longer sleep calls, use this Skill to trace the data flow, find the actual timing dependency, and replace arbitrary timeouts with condition-based polling. ## 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 debug a test failure 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 verified fix. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by race conditions?▼

Replace arbitrary timeouts like setTimeout or sleep with condition-based waiting that polls for the actual state you need, such as waiting for a specific event count. The included condition-based-waiting technique took one suite from 60% to 100% pass rate.

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

Stop and return to root cause investigation 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 before attempting another fix.

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

Use the included find-polluter.sh bisection script, which runs test files one by one and checks whether unwanted files or directories appear after each run. It stops at the first test that creates the pollution and reports the culprit.

When is it acceptable to skip root cause investigation for simple bugs?▼

Never, according to this methodology. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation even under emergency time pressure leads to symptom fixes that guarantee rework.