Before any plan is written, dispatch parallel read-only agents to verify what actually exists on disk — so the plan names real paths, not plausible fiction.

Pattern

Scout Swarm

The failure mode

A planner writing from memory is a generator of plausible fiction.

Plan written from memorypaths invented

✗services/auth.pydoesn't exist

✗utils/validators.tsoff by dir

?models/User"probably"

?lib/middleware"I think"

Plausible paths, phantom files. The builder follows the plan into ghost territory — creates a duplicate services/auth.py; the real lib/auth_service.py is untouched.

Plan written from scout findingspaths verified

✓lib/auth_service.pyL42–L118

✓src/validation/user.tsL7

✓db/models/user.pyL15

✓app/middleware/auth.pyL3

Exact paths, line numbers, zero guesses. The plan names what disk actually contains. The builder operates on real files in their real locations.

The shape

One parallel dispatch — deep comprehension and wide coverage at once.

The standard swarm: 3 Opus scouts where comprehension matters, 5 Haiku scouts where surface area matters. All fired in ONE dispatch — not serial.

⚡ONE parallel dispatch  ·  8 scouts  ·  no serial waiting

BASE SCOUTS3 · Opus

Deep comprehension. Read nuance, synthesize structure.

S1Entry points, config, CLAUDE.md

S2Area most relevant to the prompt

S3Tests, deps, similar code

FAST SCOUTS5 · Haiku

Wide coverage. Read more surface area cheaply.

F1dir-A · patterns

F2dir-B · imports

F3dir-C · utilities

F4dir-D · schemas

F5dir-E · remaining

Ratios adjust to the task — a simple bug fix may need 2 scouts; a cross-cutting feature may deploy more. What doesn't change: the swarm fires in one parallel shot.

Why scouts can't hallucinate

Read-only is a structural constraint, not a courtesy.

The tool allowlist is what makes scout findings trustworthy. Their output is bounded by what the tools returned.

✓ Granted

ReadGlobGrep

✗ Denied

WriteEditBashTaskWebFetch

A scout's only output is a report. It cannot modify files, cannot execute state-changing commands, cannot write to the plan. The planner owns the write surface — scouts feed the planner, they don't replace it.

The anti-hallucination gate

Scout reports are claims. The planner validates them on disk first.

After scouts report — and before the plan is written — the planner runs each flagged file past Read to confirm it exists and contains what the scout claimed.

1. Reportsscout claims

S1auth in lib/auth_service.py

S2validator in src/util.ts

S3User model in db/user.py

F2middleware in app/mw.py

F4schema in shared/types.ts

→

verify

2. Validateread each flagged file

1 open path with Read

2 confirm file exists

3 confirm claim is present

4 capture exact line numbers

5 discard what misses

→

verified

3. Planverified-only

✓lib/auth_service.py:42

✗src/util.ts — not found

✓db/user.py:15

✓app/mw.py:3

✓shared/types.ts:88

The pass is cheap — files are already named. It catches scout errors before they propagate into the plan, and the plan is written from the validated list only.

When to deploy

The swarm isn't free — but misread paths aren't either.

Deploy scouts

• Any medium or complex implementation plan
• Codebase has more than ~20 relevant files
• Task modifies existing files — wrong paths are expensive
• Before an orchestrated builder pipeline — scouts inform the plan that drives them

Skip the swarm

• Trivial one-file change you can name outright
• Planner already has all relevant paths in context from prior turns
• Greenfield — no existing files to misidentify
• You'd rather hand-tune the scout assignments than run the standard 3+5

Writing a plan directly from memory is the anti-pattern — a generative model will always produce plausible-sounding paths, existent or not.

The discipline

A plan is only as accurate as the disk reads it was written from.

Scout in parallel with read-only agents. Validate every flagged path by opening the file. Write the plan from verified findings — exact paths, exact line numbers, no approximations. The planner stops generating fiction and starts writing fact.