systematic-debugging

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

Updated Mar 2, 2026
One-click install
npx skills add https://github.com/LeroyAdonis/kitfix-2.0 --skill systematic-debugging-leroyadonis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/LeroyAdonis/kitfix-2.0/tree/main/.github/skills/systematic-debugging
Command: npx skills add https://github.com/LeroyAdonis/kitfix-2.0 --skill systematic-debugging-leroyadonis

SYSTEM DOCUMENTATION & REQUIREMENTS

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

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 take shortcuts. ## Core Features & Use Cases - Four-Phase Process: Structured workflow covering Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation, with explicit gates between phases. - Pressure-Resistant Rules: Anti-patterns, red flags, and rationalization tables that catch shortcut behavior like "just one quick fix" or shotgun debugging. - Supporting Techniques: Includes root-cause tracing through call stacks, defense-in-depth validation at multiple layers, condition-based waiting to replace flaky timeouts, and a test-polluter bisection script. - Use Case: A test fails intermittently in CI. Instead of adding arbitrary sleep delays, follow Phase 1 to reproduce and gather evidence, trace the bad value to its source, form a single hypothesis, and verify the fix with a failing test case. ## Quick Start Ask the AI to debug a failing test or production bug using the systematic-debugging skill and require root cause investigation before any fix is proposed.

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 verified by a failing test case. Never propose fixes before completing Phase 1.

What is root cause tracing in debugging?▼

Root cause tracing follows a bug backward through the call stack to find the original trigger rather than fixing where the error appears. Add stack trace instrumentation with console.error before the failing operation, then trace each caller until you find where the bad value originated.

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 condition you need, such as an event appearing or state changing. The skill includes a waitFor polling pattern and examples that fixed 15 flaky tests with a 100% pass rate.

Should I skip investigation when production is down and losing money?▼

No. The skill explicitly addresses this pressure scenario: systematic investigation is faster than guess-and-check thrashing, and quick symptom fixes often fail or create new bugs. The process is designed to resist exactly this rationalization.

What should I do when three or more fix attempts have failed?▼

Stop attempting more fixes and question the architecture. Three or more failures with each fix revealing new problems elsewhere indicates a structural issue, not a bad hypothesis. Discuss refactoring the pattern with your team before continuing.

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

Use the included find-polluter.sh bisection script, which runs test files one by one and checks whether the unwanted file or directory appears after each run. It stops at the first polluting test and prints investigation commands.