Parallel fanout verification

Parallel Fanout Verification

When to use

• A change touches more than one layer (backend + frontend + E2E + live integration).
• You have two or more independent bugs to fix on the same branch.
• Any verification task would produce log spam (torch, chromadb, vite, huggingface) large enough to crowd out useful context.
• You are about to run pytest, vitest, and Playwright sequentially in the main thread.

When NOT to use

• The task is a single, trivial, self-contained change (one file, one assertion).
• You genuinely need the output of step N before you can begin step N+1 (sequential dependency — rare, but real).
• You are already inside a sub-agent dispatched from a parent — nesting deep fanouts without coordination creates race conditions on shared files.

How to apply

Fanning out test layers

Dispatch one Agent-tool call per test suite, all with run_in_background: true:

Agent 1: "Run pytest tests/ -q. Report: count passed/failed, first 10 lines
          of any failure. ≤250 words."
Agent 2: "cd ui/frontend && npm test -- --run. Same format."
Agent 3: "npx playwright test. Same format."
Agent 4: "Live integration: hit /api/health, /api/corpus/search (empty corpus),
          /api/setup/state. Report HTTP status codes only."

Continue with other work while all four run. Merge their reports when notifications arrive — don't tail transcript files (that overflows context).

Fanning out fixes

Carve lanes by file ownership so agents don't conflict:

Agent	Owns
Agent A	backend/**, tests/**
Agent B	ui/frontend/src/**, *.test.tsx
Agent C	e2e/**, Playwright helpers

One agent per logical bug. Brief each agent with: the bug description, the files it owns, and "commit when done — one atomic commit with a why-first message."

The parent collects completion notifications, then fans out a single verification pass over all three branches (see [[pre-handoff-clean-state-proof]]).

The "fix agent AND verifier agent" pattern

When you are not certain a fix will work, dispatch the fix agent AND a verifier agent simultaneously. The verifier checks the live system as it stands; the fix agent lands the change. If the verifier reports failure AFTER the fix lands, that's a regression — GOTO [[fix-first-then-test]].

Why this works

The main conversation context is finite. Multi-minute test suites produce thousands of lines of log output (framework startup, deprecation warnings, test summaries). Running them inline burns context that cannot be recovered and serializes work that could complete in parallel. Dispatching agents keeps the main thread free for reasoning while the harness runs.

Anti-patterns to avoid

• "I'll just run one test suite inline to check" — this is how log spam kills sessions. Always dispatch, even for a single-suite run.
• Overlapping file ownership — two agents editing the same file creates merge conflicts on shared state. Define lanes before dispatching.
• Forgetting to wait for all notifications — claiming the fix is complete after only some agents have reported. Every agent must report before handoff.
• Tailing transcript files — the system warning is real; transcripts overflow context. Read the notification summary instead.

Cross-links

• [[fix-first-then-test]] — fanout is for verification, not for discovering bugs
• [[pre-handoff-clean-state-proof]] — the final gate before handing back to the user
• [[agent-model-selection]] — pass model: explicitly when dispatching agents