systematic-debugging

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

Updated May 23, 2026
One-click install
npx skills add https://github.com/Oatse/CWE-Automation --skill systematic-debugging-oatse
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/Oatse/CWE-Automation/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/Oatse/CWE-Automation --skill systematic-debugging-oatse

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 escalation to architectural review after three failed fixes. - Use Case: A test suite has flaky failures caused by arbitrary sleep calls. Use this Skill to trace the actual async condition, replace timeouts with condition polling, and add validation layers so the bug cannot recur. ## 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 fixing symptoms?

Follow the four-phase process: read error messages and reproduce the issue, analyze patterns against working examples, form and test a single hypothesis, then implement one verified fix. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by setTimeout and sleep calls?

Replace arbitrary timeouts 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, and only use fixed delays when testing documented timing behavior.

What should I do when my first bug fix doesn't work?

Stop and return to root cause investigation with the new information rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss the design with your team before attempting another fix.

How do I trace a bug that appears deep in the call stack?

Trace backward from the immediate cause by asking what called each function and what values were passed, until you find the original trigger. Add stack trace instrumentation with console.error before the failing operation, and fix at the source rather than the symptom point.

When should I add validation at multiple layers of my code?

Add defense-in-depth validation after fixing a bug caused by invalid data, placing checks at the entry point, business logic, environment guards, and debug instrumentation. Single-point validation can be bypassed by other code paths, mocks, or refactoring.

Is it okay to skip systematic debugging for simple bugs or emergencies?

No. The process treats simple bugs and emergencies as the most important times to investigate, since rushing guarantees rework and guess-and-check thrashing is slower than systematic diagnosis. Symptom fixes are defined as failure.