systematic-debugging

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

Updated Mar 31, 2026
One-click install
npx skills add https://github.com/SESELOVSKYDarian/Vase --skill systematic-debugging-seselovskydarian
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/SESELOVSKYDarian/Vase/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/SESELOVSKYDarian/Vase --skill systematic-debugging-seselovskydarian

SYSTEM DOCUMENTATION & REQUIREMENTS

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 apply a quick workaround. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and implementation, with mandatory completion of each phase before proceeding. - Supporting Techniques: Includes root-cause-tracing (backward call-stack tracing), defense-in-depth validation at multiple layers, and condition-based waiting to replace flaky arbitrary timeouts in tests. - Pressure Resistance: Explicit anti-patterns, red flags, and rationalization tables that stop shortcut behavior during emergencies, plus a rule to question the architecture after 3+ failed fixes. - Use Case: A test suite has flaky failures caused by arbitrary sleep calls. Use this Skill to trace the root cause, replace timeouts with condition-based polling, and add layered validation so the bug cannot recur. ## 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 case. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by setTimeout and sleep calls?

Replace arbitrary timeouts with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. Poll every 10ms with a clear timeout error, and only use fixed delays when testing documented timing behavior.

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 or creating files?

Use the included find-polluter.sh bisection script, which runs test files one by one and stops at the first test that creates the unwanted file or directory. Then trace the call chain backward to find where the invalid value originated.

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

According to this methodology, never. Emergencies and simple bugs still require the process because systematic investigation is faster than guess-and-check thrashing, and symptom fixes mask the real problem while creating new bugs.