gitwalter Skill: Systematic Debugging (Superpowers Port)
When to Use
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Prevents "guessing" and ensures scientific investigation.
Prerequisites
- Reproducible failure or clear symptom.
- Access to logs, code, and recent diffs.
Process
The systematic debugging process consists of four distinct phases of investigation and implementation.
Phase 1: Root Cause Investigation
- Read Error Messages: Don't skip. Read the whole stack trace.
- Reproduce Consistently: Find the exact steps to trigger the failure.
- Check Recent Changes:
git diffis your best friend. - Evidence Gathering: For multi-layer systems, log data at every boundary.
Phase 2: Pattern Analysis
- Working Examples: Find code that does work and compare.
- Read References: Read the pattern/documentation completely. Don't skim.
- Identify Differences: List every difference between working and broken code.
Phase 3: Hypothesis and Testing
- Single Hypothesis: "I think X is the root cause because Y."
- Minimal Test: Make the smallest possible change to test the hypothesis.
- Verify: If it didn't work, REVERT and form a NEW hypothesis.
Phase 4: Implementation
- Create Failing Test: Reproduce the bug with an automated test (TDD Rigor).
- Implement Fix: Singular fix for the root cause.
- Verify Fix: Confirm pass and no regressions.
Best Practices
Follow these best practices to maintain a rigorous debugging standard.
Questioning Architecture
If 3+ fixes have failed: STOP.
- Is the pattern fundamentally sound?
- Are we fixing symptoms of a broken architecture?
- Discuss with your human partner before attempting Fix #4.
Axiomatic Alignment
- Truth: We don't guess; we investigate.
- Beauty: Orderly investigation leads to cleaner, more stable systems.