# Systematic Debugging

Find the root cause of a bug or test failure before proposing any fix.

- Repository: https://github.com/obra/superpowers (310584 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add obra/superpowers --skill systematic-debugging -g -a claude-code -y`
Codex: `npx skills add obra/superpowers --skill systematic-debugging -g -a codex -y`
Cursor: `npx skills add obra/superpowers --skill systematic-debugging -g -a cursor -y`
Gemini CLI: `npx skills add obra/superpowers --skill systematic-debugging -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add obra/superpowers`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Systematic Debugging

## Overview

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't completed Phase 1, you cannot propose fixes.

## When to Use

Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

**Don't skip when:**
- Issue seems simple (simple bugs have root causes too)
- You're in a hurry (rushing guarantees rework)
- Manager wants it fixed NOW (systematic is faster than thrashing)

## The Four Phases

You MUST complete each phase before proceeding to the next.

### Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

1. **Read Error Messages Carefully**
   - Don't skip past errors or warnings
   - They often contain the exact solution
   - Read stack traces completely
   - Note line numbers, file paths, error codes

2. **Reproduce Consistently**
   - Can you trigger it reliably?
   - What are the exact steps?
   - Does it happen every time?
   - If not reproducible → gather more data, don't guess

3. **Check Recent Changes**
   - What changed that could cause this?
   - Git diff, recent commits
   - New dependencies, config changes
   - Environmental differences

4. **Gather Evidence in Multi-Component Systems**

   **WHEN system has multiple components (CI → build → signing, API → service → database):**

The rest: https://github.com/obra/superpowers/blob/HEAD/skills/systematic-debugging/SKILL.md