systematic-debugging

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

Updated Oct 16, 2025
One-click install
npx skills add https://github.com/hugotown/dotfiles --skill systematic-debugging-hugotown
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/hugotown/dotfiles/tree/main/agents/skills/systematic-debugging
Command: npx skills add https://github.com/hugotown/dotfiles --skill systematic-debugging-hugotown

SYSTEM DOCUMENTATION & REQUIREMENTS

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 across layers, and condition-based waiting to replace flaky arbitrary timeouts. - Pressure Resistance: Built-in red flags, rationalization tables, and architectural escalation rules (question the design after 3 failed fixes) that hold up under deadlines and authority pressure. - Use Case: When a test fails intermittently in CI, instead of adding sleep calls, trace the data flow backward, form a single hypothesis, create a failing test, and fix the source with validation at every layer. ## 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 fix with a failing test. Never propose fixes before completing the investigation phase.

How to 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 pattern, such as ./find-polluter.sh '.git' 'src/**/*.test.ts'. It runs each test file individually and stops at the first one that creates the unwanted file or directory.

What should I do when my first 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 design with your team before attempting another fix.

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 expected state, such as an event count or status value. The included condition-based-waiting technique raised one suite's pass rate from 60% to 100% while running 40% faster.

When is it acceptable to skip root cause investigation for a quick fix?▼

According to the skill, never. Even under production emergencies or time pressure, systematic investigation is faster than guess-and-check thrashing, and symptom fixes are explicitly defined as failure.