systematic-debugging

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

Updated Mar 24, 2026
One-click install
npx skills add https://github.com/AarushiShah/coding-agents-databricks-apps --skill systematic-debugging-aarushishah
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/AarushiShah/coding-agents-databricks-apps/tree/main/.claude/skills/systematic-debugging
Command: npx skills add https://github.com/AarushiShah/coding-agents-databricks-apps --skill systematic-debugging-aarushishah

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 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. - Supporting Techniques: Includes root cause tracing through call stacks, 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 fixes during emergencies, plus a rule to question the architecture after three failed fix attempts. - Use Case: When a test fails intermittently in CI, use this Skill to trace the failure back through the call chain, form a single hypothesis, create a failing test case, and fix the source rather than adding another sleep timeout. ## 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-phase process: first investigate the root cause by reading errors and reproducing the issue, then analyze patterns against working examples, form a single hypothesis and test it minimally, and finally implement one fix with a failing test case to verify it.

How to fix flaky tests caused by arbitrary timeouts?

Replace setTimeout or sleep calls with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. The included waitForEvent helpers poll every 10ms with a timeout, which fixed 15 flaky tests and raised pass rates from 60% to 100%.

Should I apply a quick fix during a production emergency?

No. The skill mandates root cause investigation first because systematic debugging is faster than guess-and-check thrashing, and symptom fixes mask the real issue. Quick patches set a bad pattern and typically create new bugs.

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 a new problem elsewhere indicate a fundamentally wrong pattern, which should be discussed before continuing.

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 checks whether the unwanted file or directory appears after each run. It stops at the first polluting test and reports the file responsible.