Systematic Debugging

---
# moe-generated: sha=6afaf038bad7
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

# Systematic Debugging

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

Symptom fixes mask underlying issues and create new bugs. If you haven't completed Phase 1, you cannot propose a fix.

## When To Use

Any bug, test failure, build break, integration issue, or unexpected behaviour. Especially under time pressure — systematic is faster than guess-and-check thrashing.

## The Four Phases

Complete each phase before the next. No skipping.

### Phase 1 — Root Cause Investigation

- Read every error message and stack trace fully. Note line numbers, file paths, error codes.
- Reproduce consistently. Document exact steps. If you can't reproduce, gather more data — don't guess.
- Check recent changes: `git diff`, recent commits, new dependencies, config changes, environmental differences.
- Multi-component systems: instrument every component boundary (log inputs, log outputs, verify env/config propagation, check state per layer). Run once, identify which component breaks, then investigate that one.
- Trace data flow upward: where does the bad value originate? Fix at the source, not the symptom.

### Phase 2 — Pattern Analysis

- Find a working example of the same pattern in this codebase.
- Read reference implementations completely (no skimming).
- List every difference between working and broken — however small. Don't dismiss "that can't matter".
- Map the dependencies, settings, and assumptions the working example needs.

### Phase 3 — Hypothesis & Testing

- State one specific hypothesis: "I think X is the root cause because Y." Write it down.
- Test minimally — the smallest possible change to confirm or refute.
- One variable at a time. Don't bundle fixes.
- Worked? → Phase 4. Didn't work? → Form a NEW hypothesis. Don't pile fixes on top.
- Don't know? Say so. Don't pretend.

### Phase 4 — Implementation

- Write a failing test that reproduces the bug (use `test-driven-development`).
- Apply ONE fix that addresses the root cause. No "while I'm here" improvements.
- Verify: test passes, no other tests broken, issue actually resolved (use `verification-before-completion`).
- If the fix fails: STOP. Count attempts. <3: return to Phase 1 with the new information. ≥3: question the architecture before any further attempt — repeated failures often signal a wrong design, not a missing fix. Discuss with the human.

## Red Flags — STOP and return to Phase 1

- "Quick fix now, investigate later."
- "Just try changing X and see."
- Multiple changes at once.
- "Skip the test, I'll manually verify."
- "It's probably X."
- Proposing solutions before tracing data flow.
- "One more attempt" after 2+ failures.
- Each new fix surfacing a new problem in a different place — architectural smell.

---

## Moe integration

Trigger this skill when:

- A worker repeatedly fails the same step.
- A task lands in `BLOCKED` for a non-trivial reason.
- A `qa_reject` returns bug-shaped `rejectionDetails` (not "missing test" or "missing doc").
- A worker is reopened (`reopenCount > 0`).

Do not propose a fix in `moe.complete_step` until Phase 1 is complete. If you cannot find the root cause, call `moe.report_blocked` with what you investigated — better than a guessed fix that wastes another QA round-trip.