root-cause-before-fixes

name	root-cause-before-fixes
description	Use when encountering any bug, test failure, hook misbehavior, or unexpected output — BEFORE proposing or applying any fix, even a one-liner that looks obvious. Also use when a fix you tried didn't work, and especially after a third failed attempt.

Root cause before fixes

Iron Law: no fixes without root-cause investigation first. A fix applied to a symptom costs three later sessions; five minutes of tracing costs five minutes.

Phases (in order, no skipping)

1. Reproduce and READ the actual error. The real message, the real exit code, the real line — not your memory of similar errors. On this repo the transcript keeps every failure; quote it to yourself before theorizing.
2. Pull what's known. py agent_cli.py recall-at --path <file> (or --command "...") surfaces prior lessons and anti-patterns for this exact target — someone may have paid for this bug already. (Hooks do this automatically before Edit/shell actions; pull manually when investigating.)
3. Trace to the cause, not the site. Compare against the nearest WORKING analog (a passing test, a sibling module) and diff the assumptions.
4. State a single hypothesis out loud: "I think X is the root cause because Y." If you cannot say Y, you are not done investigating.
5. Fix with evidence. Failing test (or failing command) first, watch it fail, apply the fix, watch it pass. An Edit that "should" fix it is a hypothesis, not a fix.

Red-flag rationalizations (stop when you hear yourself think these)

• "Just try this first, then investigate if it doesn't work"
• "I don't fully understand it, but this might work"
• "It's probably the same issue as before" (verify — this repo's history rewrote SHAs once)
• "The error is misleading" (errors are evidence; your model of the code is the suspect)

The 3-strikes escalation

After three failed fix attempts on the same target: stop patching and question the architecture. State what invariant the design assumed that reality violated. Record it — that insight is an anti-pattern lesson:

py agent_cli.py learn <id> --experiment <slug> --anti-pattern <slug> \
    --tried "3 fixes that failed: ..." --result "the design assumption that was wrong" \
    --recommend "Use when <symptom> recurs: question <assumption> before patching."

When the fix lands

The FAIL→SUCCESS flip auto-credits whatever lessons were surfaced (the funnel is watching). If the fix generalizes, record it while the context is loaded — the hook's pre-filled learn command is one edit away from done.