systematic-debugging

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

1|Updated Oct 11, 2025
One-click install
npx skills add https://github.com/ibytechaos/claude --skill systematic-debugging-ibytechaos
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/ibytechaos/claude/tree/main/plugins/superpowers/skills/systematic-debugging
Command: npx skills add https://github.com/ibytechaos/claude --skill systematic-debugging-ibytechaos

SYSTEM DOCUMENTATION & REQUIREMENTS

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 root causes before any fix is attempted, even under time pressure or authority pressure. ## 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. - Pressure Resistance: Red flags, rationalization tables, and anti-pattern lists that stop shortcut fixes during emergencies, plus a rule to question the architecture after 3+ failed fixes. - Use Case: When a production test fails intermittently, follow Phase 1 to reproduce and gather evidence, trace the bad value to its source, form a single hypothesis, and verify the fix with a failing test instead of stacking sleep() calls. ## 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 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 stack multiple fixes at once.

How to find the root cause of a bug deep in the call stack?

Trace backward through the call chain from the immediate cause to the original trigger, asking what called each level and what value was passed. Add stack trace instrumentation with console.error before the failing operation if manual tracing stalls.

Should I skip root cause investigation during a production emergency?

No. Systematic debugging is faster than guess-and-check thrashing even under time pressure. Quick symptom fixes set a bad pattern, mask the real issue, and typically cause rework and new bugs.

How do I fix flaky tests caused by timing issues?

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. Only use fixed delays when testing documented timing behavior.

What should I do when three or more fix attempts have failed?

Stop attempting more fixes and question the architecture. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, so discuss refactoring with your team before trying fix number four.

When is a single validation check not enough after fixing a bug?

Single-point validation can be bypassed by other code paths, mocks, or refactoring. Apply defense-in-depth by validating at every layer data passes through: entry points, business logic, environment guards, and debug instrumentation.