| 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.