Systematic Debugging

Overview

This skill provides a structured four-phase debugging framework emphasizing root cause discovery before attempting fixes. Core principle: "Random fixes waste time and create new bugs. Quick patches mask underlying issues."

Quick Start

1. Investigate - Gather evidence, reproduce consistently
2. Analyze - Compare with working patterns
3. Hypothesize - Form and test specific theories
4. Implement - Fix with test coverage

When to Use

• Bug reports requiring investigation
• Test failures with unclear causes
• Production incidents
• Performance regressions
• Integration failures
• Any debugging that requires more than 5 minutes

The Four Phases

Phase 1: Root Cause Investigation

Objective: Understand the problem completely before attempting any fix.

Steps:

1. Examine error messages thoroughly
2. Reproduce the issue consistently
3. Review recent changes (commits, configs, dependencies)
4. Gather diagnostic evidence (logs, traces, metrics)
5. For multi-component systems, add instrumentation at each boundary

Questions to answer:

• What exactly is failing?
• When did it start failing?
• What changed recently?
• Can I reproduce it reliably?

Phase 2: Pattern Analysis

Objective: Find working examples and understand differences.

Steps:

1. Locate working examples in the codebase
2. Compare against reference implementations completely
3. Identify differences systematically
4. Understand all dependencies

Key comparisons:

• Working vs. broken code paths
• Expected vs. actual behavior
• Known good state vs. current state

Phase 3: Hypothesis and Testing

Objective: Form and validate theories before changing code.

Steps:

1. Formulate a specific hypothesis
2. Design a test for the hypothesis
3. Test with minimal changes (one variable at a time)
4. Verify results before proceeding

Hypothesis format: "The bug occurs because [condition] when [trigger], which causes [symptom]."

Phase 4: Implementation

Objective: Fix the root cause with proper verification.

Steps:

1. Create a failing test case reproducing the bug
2. Implement a single fix addressing the root cause
3. Verify the test passes
4. Verify no other tests broke
5. Document the fix

Critical Safeguards

Hard Stop Rule

If >= 3 fixes fail: STOP and question the architecture.

When multiple fixes fail, the issue indicates deeper structural problems requiring discussion rather than continued symptom-patching.

Red Flags (Restart Process)

• Proposing solutions before investigation
• Attempting multiple simultaneous fixes
• Assuming without verification
• Skipping reproduction step
• "It should work" without evidence

Debugging Anti-Patterns

Instrumentation Strategies

Logging Strategy

1. Entry/exit of suspected functions
2. Input/output values at boundaries
3. State changes at key points
4. Timing information for performance issues

Boundary Tracing

For multi-component systems:

[Input] -> [Component A] -> [Component B] -> [Output]
   ^            ^               ^              ^
   |            |               |              |
 Check 1     Check 2         Check 3       Check 4

Add verification at each boundary to isolate failure point.

Debugging Checklist

• Issue reproduced consistently
• Recent changes reviewed
• Error messages fully understood
• Working comparison found
• Hypothesis documented
• Single-variable test performed
• Root cause identified
• Failing test written
• Fix implemented
• All tests pass
• Fix documented

Related Skills

• tdd-obra - Test-first development
• writing-plans - Plan implementations
• code-reviewer - Code quality review

Version History

• 1.0.0 (2026-01-19): Initial release adapted from obra/superpowers

Sub-Skills

• Best Practices
• Error Handling
• Metrics