systematic-debugging

name	systematic-debugging
description	Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

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.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

The Four Phases

Phase 1: Root Cause Investigation

Before attempting ANY fix:

1. Read error messages carefully
2. Reproduce consistently
3. Check recent changes
4. Gather evidence in multi-component systems
5. Trace data flow

Phase 2: Pattern Analysis

1. Find working examples
2. Compare against references
3. Identify differences
4. Understand dependencies

Phase 3: Hypothesis and Testing

1. Form single hypothesis
2. Test minimally
3. Verify before continuing
4. If you don't know, say so

Phase 4: Implementation

1. Create failing test case
2. Implement single fix
3. Verify fix
4. If fix doesn't work, return to Phase 1
5. If 3+ fixes failed, question architecture

Red Flags - STOP and Follow Process

If you catch yourself thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "It's probably X, let me fix that"

All of these mean: STOP. Return to Phase 1.

Supporting Techniques

• root-cause-tracing.md
• defense-in-depth.md
• condition-based-waiting.md

Related skills:

• test-driven-development
• verification-before-completion