systematic-debugging

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

Updated Jun 9, 2026
One-click install
npx skills add https://github.com/gyc-12/Archipelago --skill systematic-debugging-gyc-12
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/gyc-12/Archipelago/tree/main/modules/collaboration-runtime/src-tauri/experts/skills/systematic-debugging
Command: npx skills add https://github.com/gyc-12/Archipelago --skill systematic-debugging-gyc-12

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 just patch the symptom. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and verified 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: A test suite has flaky failures caused by race conditions. Instead of adding longer sleep delays, apply condition-based waiting to poll for actual events, trace the failure to its source, and add validation at every layer the bad data passes through. ## Quick Start Ask the AI to debug a failing test or production bug using the systematic-debugging process, starting with root cause investigation before proposing 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 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 event or state you need. The included waitForEvent utilities poll every 10ms with a timeout, which raised one test suite's pass rate from 60% to 100%.

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

Stop and return to Phase 1 to re-analyze 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 fundamental design before attempting another fix.

How do I find which test is polluting shared state or creating files?

Use the included find-polluter.sh bisection script, which runs each test file individually and checks whether the unwanted file or directory appears. It stops at the first polluting test and reports the file for investigation.

When is it acceptable to skip root cause investigation for a quick fix?

According to the skill, never. Even during production emergencies, systematic investigation is faster than guess-and-check thrashing, and symptom fixes are defined as failure regardless of time pressure.