systematic-debugging

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

Updated Aug 25, 2026
One-click install
npx skills add https://github.com/AliJ021/labelmod-core --skill systematic-debugging-alij021
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/AliJ021/labelmod-core/tree/main/.claude/skills/systematic-debugging
Command: npx skills add https://github.com/AliJ021/labelmod-core --skill systematic-debugging-alij021

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers under time pressure often apply quick symptom fixes that fail repeatedly, causing thrashing, regressions, and wasted hours. This Skill enforces a disciplined 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, single-hypothesis testing, and verified implementation with failing test cases. - 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 fixes. - Use Case: When a production test fails intermittently, follow Phase 1 to reproduce and gather evidence across component boundaries, trace the bad value to its source, then fix at the origin with layered validation instead of adding another sleep timer. ## 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 errors fully and reproduce consistently, compare against working examples, form one specific hypothesis and test it minimally, then implement a single fix verified by a failing test case. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by arbitrary timeouts?

Replace setTimeout and sleep calls with condition-based waiting that polls for the actual expected state, such as an event count or status value. The included waitForEvent helpers poll every 10ms with a timeout, which raised one test suite from 60% to 100% pass rate.

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 revealing new problems in different places indicate a structural issue, so discuss the pattern with your team before continuing.

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

Use the included find-polluter.sh bisection script with the polluted path and a test file pattern. It runs each test individually and stops at the first one that creates the unwanted file or directory.

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

Never, according to the skill's rules. Simple bugs have root causes too, and the process is fast for simple cases; skipping investigation under time pressure leads to guess-and-check thrashing that takes longer overall.