skills.rest
wolfstar-project
wolfstar-projectOFFICIAL
Explore all skills by this author →
WebsiteGitHub

systematic-debugging

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

Updated Aug 8, 2026
Search Tags:#debugging#troubleshooting#root cause analysis#test failures#flaky tests#systematic process#defense in depth
One-click install
npx skills add https://github.com/wolfstar-project/code-zero --skill systematic-debugging-wolfstar-project
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/wolfstar-project/code-zero/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/wolfstar-project/code-zero --skill systematic-debugging-wolfstar-project

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 thrashing and recurring bugs. 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. - Failure Escalation: After three failed fixes, the process mandates questioning the architecture rather than attempting a fourth fix. - Use Case: When a test fails intermittently in CI, follow Phase 1 to reproduce and gather evidence, trace the bad value to its source, then fix at the origin with a failing test proving the resolution. ## Quick Start Use the systematic-debugging skill to investigate this failing test and find its root cause 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 fix verified by a failing test. Never propose fixes before completing Phase 1.

How to fix flaky tests caused by arbitrary timeouts?▼

Replace setTimeout and sleep calls with condition-based waiting that polls for the actual condition you need, such as an event appearing or state changing. The included condition-based-waiting technique raised one test suite from 60% to 100% pass rate while running 40% faster.

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

Stop and return to Phase 1 with the new information rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss fundamentals with your team 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 test files one by one and stops at the first test that creates the unwanted file or directory. Combine this with stack trace instrumentation before the dangerous operation.

When is it acceptable to skip root cause investigation for simple bugs?▼

Never, according to this methodology. 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.

Related Skills

Explore More Software Engineering Skills→
YaugourtYaugourt
2

investigate

Identify root causes of bugs by analyzing logs and code paths.

Community
Advanced
guardiatechnologyguardiatechnology

kata-python-debug

Diagnose Python bugs by writing a failing regression test and verifying fixes with ruff and mypy.

Official
Advanced
cwinvestmentscwinvestments
412

verify

Automate pre-commit verification with build, test, and lint checks.

Community
Intermediate
apdarrapdarr

debugging

Diagnose Rails 8 issues via log analysis, console debugging, and breakpoints.

Community
Intermediate