01 ▸ Workflow Position
[Bug / Test Failure]
│
▼
┌─────────────────────────────┐
│ Systematic Debugging (ACTIVE)│
│ 7-Step Root Cause Search │
└──────────────┬──────────────┘
│
▼
[DONE]
02 ▸ When to use?
Use when encountering any bug, test failure, or unexpected behavior. Enforces a strict reproduce-first, root-cause-first workflow.
Main Triggers
- Any test failure
- Production or local bug reports
- Unexpected state, rendering, or query results
- Performance degradation or intermittent failures
03 ▸ How it works?
Core Principle: Fix the cause, not the symptom. Prevent guess-based fixes by locking the failure with a test first.
Execution Steps
- Define the Problem: Expected vs. Observed behavior in one sentence.
- Reproduce or Instrument: Must see the failure again before fixing. Smallest path possible.
- Gather Evidence: Collect observable facts — stack traces, logs, boundary inputs/outputs.
- Isolate Root Cause: Formulate exactly one hypothesis based on evidence.
- Lock the Failure: Create an automated failing test (or reproduction script) before fixing.
- Implement a Single Fix: Minimal change addressing only the isolated hypothesis.
- Verify and Close: Confirm the reproduction path no longer fails and related tests pass.
Hard Gates:
- Do not fix until you have a reproducible state.
- Do not fix until you have a root-cause hypothesis.
- Do not fix until you have a failing guard (test).
- Verify only one hypothesis at a time.
- No "while I'm here" refactoring during a fix.