# Systematic Debugging

> Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.

- Skill: `gitwalter/systematic-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gitwalter/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitwalter/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gitwalter (https://skillmd.com/u/gitwalter)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gitwalter/systematic-debugging

---


# 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
1.  **Read Error Messages**: Don't skip. Read the whole stack trace.
2.  **Reproduce Consistently**: Find the exact steps to trigger the failure.
3.  **Check Recent Changes**: `git diff` is your best friend.
4.  **Evidence Gathering**: For multi-layer systems, log data at every boundary.

### Phase 2: Pattern Analysis
1.  **Working Examples**: Find code that *does* work and compare.
2.  **Read References**: Read the pattern/documentation completely. Don't skim.
3.  **Identify Differences**: List every difference between working and broken code.

### Phase 3: Hypothesis and Testing
1.  **Single Hypothesis**: "I think X is the root cause because Y."
2.  **Minimal Test**: Make the smallest possible change to test the hypothesis.
3.  **Verify**: If it didn't work, REVERT and form a NEW hypothesis.

### Phase 4: Implementation
1.  **Create Failing Test**: Reproduce the bug with an automated test (TDD Rigor).
2.  **Implement Fix**: Singular fix for the root cause.
3.  **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.