systematic-debugging

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

1|Updated May 3, 2021
One-click install
npx skills add https://github.com/leogurja/dotfiles --skill systematic-debugging-leogurja
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/leogurja/dotfiles/tree/main/home/dot_agents/skills/systematic-debugging
Command: npx skills add https://github.com/leogurja/dotfiles --skill systematic-debugging-leogurja

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, wasting hours on 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 stop shortcut behavior during emergencies, plus a bisection script to find which test pollutes shared state. - Use Case: A test suite fails intermittently in CI. Instead of adding longer sleep calls, follow Phase 1 to gather evidence across components, trace the bad value to its source, then fix it once with a failing test proving the resolution. ## 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 a four-phase process: 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 arbitrary timeouts?▼

Replace setTimeout and sleep calls with condition-based waiting that polls for the actual condition you need, such as an event appearing or state changing. Poll every 10ms with a clear timeout error, which eliminates race conditions and typically speeds up test execution.

What should I do when my first fix does not work?▼

Stop and form a new hypothesis rather than stacking additional fixes. If three or more fixes have failed, treat it as an architectural problem and question the fundamental design with your team before attempting another fix.

How do I find which test creates unwanted files or state?▼

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

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

Never. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation under time pressure guarantees rework, since symptom fixes fail and force you back to investigation anyway.

Why add validation at multiple layers after fixing a bug?▼

Single-point validation can be bypassed by different code paths, mocks, or refactoring. Defense-in-depth adds checks at entry points, business logic, environment guards, and debug instrumentation, making the same bug structurally impossible to reintroduce.