swarm-debuglisted

# swarm-debug — systematic debugging No fix without a reproduced cause. Shotgun patching is how the same bug costs twice. ## The loop 1. **Reproduce** — a command/test that shows the bug, or record explicitly why reproduction is impossible. This is the entry gate for everything below. 2. **Evidence** — read the FULL error, stack, and surrounding logs (not the first line); note what changed recently (git log, new deps, config). 3. **Locate** — binary-search the causal chain: which layer last had correct data? Instrument with targeted prints/asserts if needed; remove them after. 4. **Hypothesize** — ranked list, cheapest-to-test first. State each as a falsifiable claim ("the cache returns stale X when Y"). 5. **Verify** — one targeted experiment per hypothesis. Evidence kills or confirms; opinion does neither. 6. **Fix the root cause** — not the symptom, when the root is reachable. If you must ship a symptom patch, say so in the code-note and open a ticket for the root. 7. **Regression test** — must fail on the pre-fix code, pass on the fix. No test, no fix. 8. **Record (J1)** — non-trivial diagnosis → memory note (the footgun, compact, ≤ 15 lines) + code-note link on the affected file, so no future session pays for this twice. Check the vault FIRST next time: `swarmvault.py query --search "<symptom>"` — someone may already have paid. ## Hard rules - Three dead hypotheses → stop, step back, re-examine assumptions — including the spec and design