systematic-debugging

name	systematic-debugging
description	Methodical debugging instead of random changes
version	2.2.0
category	debugging
author	Jesse Vincent
license	MIT
source	https://github.com/obra/superpowers-skills/tree/main/skills/debugging/systematic-debugging
progressive_disclosure	{"entry_point":{"summary":"Replace random code changes with systematic problem diagnosis using four-phase investigation framework","when_to_use":"When user reports bugs, errors, test failures, or unexpected behavior. ESPECIALLY when under time pressure or 'quick fixes' seem obvious.","quick_start":"1. Read error messages completely 2. Reproduce consistently 3. Form specific hypothesis 4. Test with single change 5. Verify fix"},"references":["workflow.md","examples.md","troubleshooting.md","anti-patterns.md"]}
context_limit	800
tags	["debugging","problem-solving","root-cause","systematic"]
requires_tools	["debugger"]
effort	high

Systematic Debugging

Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

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

This skill enforces a four-phase systematic approach that ensures root cause investigation before any fix attempt. Violating the letter of this process is violating the spirit of debugging.

When to Use This Skill

Activate when:

• User reports a bug or error
• Test failures occur
• Code behaves unexpectedly
• Performance problems arise
• Build or integration failures
• User says "it's not working"

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

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

Core Principles

1. Reproduce First: Ensure you can reliably reproduce the issue
2. One Change at a Time: Change only one thing between tests
3. Hypothesis-Driven: Form hypotheses before making changes
4. Verify Fixes: Confirm the fix works and doesn't break anything else

Quick Start

1. Read Error Messages: Read completely, including stack traces
2. Reproduce Consistently: Create reliable reproduction steps
3. Gather Evidence: Add diagnostic instrumentation in multi-component systems
4. Form Hypothesis: State clearly "I think X because Y"
5. Test Minimally: Make smallest possible change
6. Verify Fix: Confirm resolution and no regressions

The Four Phases

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

• Read error messages carefully (they often contain the solution)
• Reproduce consistently
• Check recent changes
• Gather evidence in multi-component systems
• Trace data flow back to source

Phase 2: Pattern Analysis

Find working examples, compare against references, identify differences, understand dependencies.