Swarm debug
A shared knowledge vault + full software-engineering workflow for AI coding agents — run Claude Code and Codex in parallel with one memory, one plan.
npx -y skills add AnmarHani/SwarmVault --skill swarm-debugAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 19 days oldThe repository was created 19 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Systematic debugging — evidence before hypotheses, hypotheses before fixes, root cause before patches, and the diagnosis saved to the vault. Use for any real bug, test failure, regression, crash, or unexplained behavior — before proposing any fix.
SKILL.md
2.2 KB, as published. Nobody here has run it
swarm-debug — systematic debugging
No fix without a reproduced cause. Shotgun patching is how the same bug costs twice.
The loop
- Reproduce — a command/test that shows the bug, or record explicitly why reproduction is impossible. This is the entry gate for everything below.
- Evidence — read the FULL error, stack, and surrounding logs (not the first line); note what changed recently (git log, new deps, config).
- Locate — binary-search the causal chain: which layer last had correct data? Instrument with targeted prints/asserts if needed; remove them after.
- Hypothesize — ranked list, cheapest-to-test first. State each as a falsifiable claim ("the cache returns stale X when Y").
- Verify — one targeted experiment per hypothesis. Evidence kills or confirms; opinion does neither.
- 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.
- Regression test — must fail on the pre-fix code, pass on the fix. No test, no fix.
- 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 ("is the requirement itself contradictory?").
- A diagnosis that reveals a spec/design gap → route it to the question queue / SRS change management (swarm-spec), don't silently patch around it.
- Performance bugs: measure before and after; a fix without numbers is a guess.
Influences: superpowers systematic-debugging; Pocock's diagnosing-bugs; Jeffallan's debugging-wizard — see CREDITS.md.