systematic-debugging

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

Updated May 21, 2026
One-click install
npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill systematic-debugging-cagesthrottleus
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/CagesThrottleUs/private-ai-harness/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill systematic-debugging-cagesthrottleus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Random fixes and quick patches waste time, mask underlying issues, and create 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 patch. ## Core Features & Use Cases - Four-Phase Process: Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation, with mandatory completion of each phase before proceeding. - Pressure-Resistant Rules: Explicit red flags, rationalization tables, and anti-patterns that stop shortcut behavior like "just one quick fix" or stacking multiple changes at once. - Supporting Techniques: Includes root-cause-tracing (backward call-stack tracing), defense-in-depth validation at multiple layers, condition-based waiting to replace flaky arbitrary timeouts, and a find-polluter.sh bisection script for identifying polluting tests. - Use Case: A test fails intermittently in CI. Instead of adding sleep calls, 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. ## 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 failing test 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. Never stack multiple changes at once.

How to find the root cause of a bug deep in the call stack?

Use root cause tracing: find the immediate cause, then trace backward through each caller asking what value was passed until you reach the original trigger. Add stack trace instrumentation with console.error before the failing operation if manual tracing stalls.

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 care about, such as an event appearing or state changing. The skill includes a waitFor polling pattern and real examples that took pass rates from 60% to 100%.

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

Stop attempting more fixes and question the architecture. Three or more failures where each fix reveals new problems elsewhere indicates a structural issue, not a wrong hypothesis. Discuss the fundamental design with your team before continuing.

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

Never, according to this skill. Even under production emergencies, time pressure, or senior authority approval, systematic investigation is faster than guess-and-check thrashing. Symptom fixes are classified as failure regardless of justification.

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

Use the included find-polluter.sh bisection script with the polluted path and a test file pattern. It runs each test individually and stops at the first one that creates the unwanted file or directory.