superpowers-systematic-debugging

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

Updated May 26, 2026
One-click install
npx skills add https://github.com/avel123111/triplanio --skill superpowers-systematic-debugging-avel123111
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: superpowers-systematic-debugging
Source: https://github.com/avel123111/triplanio/tree/main/.claude/skills/superpowers-systematic-debugging
Command: npx skills add https://github.com/avel123111/triplanio --skill superpowers-systematic-debugging-avel123111

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 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: When a production test fails intermittently, use this Skill to reproduce the issue consistently, trace the bad value back through the call chain, form a single hypothesis, and verify the fix with a failing test case instead of stacking sleep timers. ## 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 superpowers-systematic-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a failing test systematically instead of guessing?

Follow the four phases: read the error completely and reproduce the failure consistently, compare against working examples in the codebase, form one specific hypothesis and test it minimally, then create a failing test case before implementing the fix. Never stack multiple changes at once.

What is root cause tracing in debugging?

Root cause tracing follows a bad value backward through the call chain until you find where it originated, then fixes the source rather than the symptom location. The skill includes stack trace instrumentation tips and a bisection script to find which test causes state pollution.

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 need, such as an event appearing or state changing. The skill provides waitForEvent and waitForEventCount helper implementations with proper timeouts.

Should I skip investigation when production is down and losing money?

No. The skill explicitly addresses this pressure scenario: systematic investigation is faster than guess-and-check thrashing, and symptom fixes during emergencies typically create more incidents. Complete Phase 1 root cause investigation before proposing any fix.

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

Stop attempting fixes and question the architecture. Repeated failures where each fix reveals a new problem elsewhere indicate a fundamentally wrong pattern, not a wrong hypothesis. Discuss architectural refactoring with your team before attempting another fix.

When is defense-in-depth validation needed after a bug fix?

Add it after fixing any bug caused by invalid data flowing through multiple layers. Validate at the entry point, business logic, environment guards, and debug instrumentation so the bug becomes structurally impossible rather than merely patched at one location.