---
name: systematic-debugging
description: Guided root-cause debugging. Use when encountering any bug, test failure, unexpected behavior, or performance problem. Enforces investigation before fixes.
---

# Systematic Debugging

No fixes without root cause. Symptom fixes mask real bugs and waste time.

## The Rule

Complete Phase 1 before proposing ANY fix. If you haven't investigated, you cannot fix.

## Phase 1: Root Cause Investigation

1. **Read error messages carefully.** Stack traces, line numbers, error codes. Don't skip past them.
2. **Reproduce consistently.** Exact steps, every time. If not reproducible, gather more data instead of guessing.
3. **Check recent changes.** Git diff, recent commits, new deps, config changes, env differences.
4. **Trace data flow.** Where does the bad value originate? Trace backward through the call stack to the source. Fix at the source, not the symptom.
5. **Multi-component systems:** Before fixing, add diagnostic logging at each component boundary (what enters, what exits). Run once to locate the failing layer, THEN investigate that layer.

## Phase 2: Pattern Analysis

1. Find working examples of similar code in the same codebase.
2. Compare working vs broken — list every difference.
3. If implementing a pattern, read the reference implementation completely, not skimmed.
4. Understand all dependencies, config, and assumptions.

## Phase 3: Hypothesis and Testing

1. State one hypothesis clearly: "X is the root cause because Y."
2. Make the smallest possible change to test it. One variable at a time.
3. If it didn't work, form a NEW hypothesis. Don't stack more fixes on top.
4. After 3 failed fixes: STOP. Question the architecture, not the symptoms.

## Phase 4: Implementation

1. Create a failing test case first (simplest reproduction).
2. Implement a single fix addressing the root cause.
3. Verify: test passes, no regressions, issue actually resolved.
4. If the fix doesn't work and you've tried 3+: the problem is architectural. Discuss before attempting more.

## Red Flags — STOP and return to Phase 1

- "Quick fix for now, investigate later"
- "Just try changing X and see"
- "I don't fully understand but this might work"
- "One more fix attempt" after 2+ failures
- Proposing solutions before tracing data flow
- Each fix reveals a new problem in a different place

## Apply This Skill

Use these tools to investigate before proposing changes:

- `view_file` to read error sites and suspect code paths
- `grep` to find all callers / references to the failing function
- `find_files` to locate related config, test fixtures, schema
- `list_dir` to understand the module layout around the bug

Report your Phase 1 findings (what you observed, what you traced, what you ruled out) before moving to Phase 3.