systematic-debugging

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

1|Updated Mar 26, 2026
One-click install
npx skills add https://github.com/arndvs/ctrlshft --skill systematic-debugging-arndvs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/arndvs/ctrlshft/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/arndvs/ctrlshft --skill systematic-debugging-arndvs

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Random fixes and guess-and-check patches waste time, mask underlying issues, and introduce new bugs. This Skill enforces a disciplined debugging methodology that finds the 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 strict gates between phases. - Root Cause Tracing: Trace bugs backward through the call stack to find the original trigger instead of patching symptoms, plus defense-in-depth validation at every layer. - Flaky Test Elimination: Replace arbitrary timeouts with condition-based waiting, and use the included bisection script to find which test pollutes shared state. - Use Case: A CI pipeline fails intermittently. Instead of retrying fixes, instrument each layer (workflow, build script, signing), gather evidence showing where data breaks, form a single hypothesis, and verify with a failing test before fixing. ## 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 guessing fixes?▼

Follow the four-phase process: read error messages fully, reproduce the issue consistently, check recent changes, and trace data flow backward through the call stack. Only after identifying the root cause should you form a single hypothesis and test it with a minimal change.

How to fix flaky tests caused by arbitrary timeouts?▼

Replace setTimeout or sleep calls with condition-based waiting that polls for the actual state you need, such as an event appearing or a count being reached. Poll every 10ms with a clear timeout error, which eliminated 15 flaky tests in the documented session.

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

Use the included find-polluter.sh bisection script with the polluted path and a test pattern, for example './find-polluter.sh .git src/**/*.test.ts'. It runs tests one by one and stops at the first test that creates the pollution.

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

Stop attempting fixes and question the architecture instead. Repeated failures where each fix reveals new problems elsewhere indicate a structural issue, so discuss refactoring the pattern with the user rather than attempting a fourth fix.

When should I add validation at multiple layers after fixing a bug?▼

Add defense-in-depth validation whenever a bug was caused by invalid data flowing through multiple components. Validate at the entry point, business logic, environment guards, and debug instrumentation layers so the bug becomes structurally impossible to reintroduce.