systematic-debugging

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

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/QT-7274/dotfiles --skill systematic-debugging-qt-7274
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/QT-7274/dotfiles/tree/main/systematic-debugging
Command: npx skills add https://github.com/QT-7274/dotfiles --skill systematic-debugging-qt-7274

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers under time pressure often apply quick symptom fixes that fail repeatedly, causing hours of 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 Implementation, with mandatory completion of each phase before proceeding. - Supporting Techniques: Includes root-cause-tracing (backward call-stack tracing), defense-in-depth validation at four layers, and condition-based waiting to replace flaky arbitrary timeouts in tests. - Bisection Script: A find-polluter.sh script that runs tests one-by-one to identify which test creates unwanted files or state. - Use Case: When a test fails intermittently or a production bug resists multiple fix attempts, load this Skill to systematically trace the failure to its source, form a single testable hypothesis, and implement one verified fix. ## 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 the four-phase process: read error messages completely, reproduce the issue consistently, check recent changes, then trace data flow backward through the call stack to the original trigger. Only form a fix hypothesis after understanding what and why.

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 care about, such as an event appearing or state changing. Poll every 10ms with a clear timeout error message.

What should I do when multiple fix attempts keep failing?▼

Stop after three failed fixes and question the architecture rather than attempting a fourth fix. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, not a failed hypothesis.

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

Use the find-polluter.sh bisection script with the pollution path and test pattern as arguments. It runs each test file individually and stops at the first test that creates the unwanted file or directory.

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

Never, according to the skill's core mandate. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation under time pressure guarantees rework through guess-and-check thrashing.