systematic-debugging

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

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

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 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: 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: A test fails intermittently in CI. Instead of adding longer sleep delays, you trace the data flow backward, find the race condition at its source, add a failing test, and fix the root cause with validation at each layer. ## Quick Start Use the systematic-debugging skill to investigate this test failure 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. Never propose fixes before completing the investigation phase.

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

Trace backward through the call chain from the symptom to the original trigger, asking what called each function and what value was passed. Add stack trace instrumentation with console.error before the failing operation, and fix at the source rather than where the error appears.

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 need, such as an event appearing or state changing. Poll every 10ms with a timeout, and only use fixed delays when testing documented timing behavior.

Should I skip root cause investigation during a production emergency?

No. Systematic debugging is faster than guess-and-check thrashing even under time pressure, since random fixes create new bugs and rarely stick. The process scales to the issue: simple bugs move through the phases quickly.

What should I do when multiple fix attempts keep failing?

Stop after three failed fixes and question the architecture rather than attempting a fourth. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, so discuss refactoring with your team before continuing.

When is defense-in-depth validation needed after fixing a bug?

Add validation at every layer data passes through after fixing a bug caused by invalid data: entry point checks, business logic validation, environment guards, and debug instrumentation. Single-point validation can be bypassed by other code paths, mocks, or refactoring.