systematic-debugging

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

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/CYRUS-pinto/pi-bot --skill systematic-debugging-cyrus-pinto
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/CYRUS-pinto/pi-bot/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/CYRUS-pinto/pi-bot --skill systematic-debugging-cyrus-pinto

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Developers under time pressure often apply quick symptom fixes that fail repeatedly, causing hours of guess-and-check thrashing. This Skill enforces a disciplined four-phase debugging methodology that finds the actual root cause before any fix is attempted. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and verified implementation with explicit gates between phases. - 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: Anti-patterns, red flags, and rationalization tables that stop shortcut fixes during emergencies, plus a rule to question the architecture after three failed fixes. - Use Case: A test suite has flaky failures from race conditions. Instead of adding longer sleep delays, use this Skill to trace the root cause and replace timeouts with condition-based polling, turning a 60% pass rate into 100%. ## 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, compare against working examples, form a single hypothesis and test it minimally, then implement one verified fix. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by race conditions?

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual expected state, such as waiting for a specific event count. This approach raised one test suite from a 60% pass rate to 100% while running 40% faster.

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 new problems elsewhere indicate a fundamental design issue that needs discussion, not another patch.

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

Trace backward from the error location through each caller, checking what values were passed at each level until you find the original trigger. Add stack trace logging with console.error before the failing operation when manual tracing is not possible.

When is it acceptable to skip systematic debugging for simple bugs?

Never. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation under time pressure leads to symptom fixes that guarantee rework and repeated failures.