systematic-debugging

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

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

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 true root cause before any fix is attempted, even under time pressure or social pressure to take shortcuts. ## 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 behavior during emergencies, exhaustion, or authority pressure. - Use Case: When a production test fails intermittently, use this Skill to trace the failure back through the call chain, form a single testable hypothesis, and fix the source rather than adding another sleep() call. ## 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 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 a single testable hypothesis, then implement one fix with a failing test case. 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 immediate cause to the original trigger, asking what called each level and what value was passed. Add stack trace instrumentation with console.error before the failing operation when manual tracing is not possible.

Should I skip root cause analysis during a production emergency?▼

No. Systematic debugging is faster than guess-and-check thrashing even under time pressure. Quick symptom fixes set a bad pattern, mask the real issue, and typically cause rework that costs more than the investigation.

Why are my tests flaky and how do I fix race conditions?▼

Flaky tests usually come from arbitrary timeouts like setTimeout that guess at timing. Replace them with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing, with a defined timeout.

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

Stop attempting more fixes and question the architecture. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, not a failed hypothesis. Discuss architectural refactoring before trying another fix.