Step 5: Fan out, then funnel

Large work can exceed one agent’s useful context. It can also help to separate the person looking for problems from the person checking whether those problems are real. Both are reasons to split the work.

The split only helps if the parts come back together. Each worker must save its findings, and a final pass must compare, verify, and combine them. That is the “funnel” in this chapter’s title. Without it, parallel work produces several temporary conversations instead of one usable result.

The shape is map-reduce with judgment at the reduce: mappers write durable partial results, and the reducer combines and verifies them.

The measured failure: fan-out findings held only in agents’ context windows. One filtered or failed agent, and its share of the work silently vanished. The rule that came out of it: every worker writes findings to disk incrementally; partial files beat perfect memory (AF-17).

Three useful patterns

1. Parallel readers, one summary. Give each agent one area of the codebase. Each writes its map to a file. A final agent reads those files, identifies disagreements, and writes the combined view. This is a safe read-only use of parallel work.

2. Find, then verify. One group proposes bugs, candidates, or edits. A different group tries to disprove each finding. The second stage prevents a large volume of plausible suggestions from becoming a large volume of bad changes (step 4).

3. A labeled background queue. Only clearly bounded tasks receive the opt-in label. A scheduled agent takes one, works on a branch, and opens a pull request. A later review accepts or closes it. A task belongs in this queue only when it has written acceptance criteria, no unresolved architecture choice, and a cheap failure mode. The worst result should be a pull request you close, not a production change you must undo.

Try it

TRY IT The vanishing findings

you

This codebase is too big for one pass. Map it so we know what we're dealing with.

agent

Six top-level areas. I can fan out one subagent per area. The question is where their findings live while the work runs.

Pick the agent's next move, then see where it leads:

ASpawning six subagents now, one per area. Each will report its map back to me when done, and I'll synthesize everything from their reports at the end.

agent

Synthesis complete: five areas mapped (core, api, ingest, ui, billing). The overview reads clean.

you

...there were six areas. Where's auth?

agent

The auth subagent hit its context limit and returned nothing. Its findings existed only in its own window, so when it died, its share of the map went with it, and the synthesis quietly stitched over the hole.

the baseline

Fan-out findings held only in agent context windows: one filtered or failed agent, and its work silently vanishes. The synthesis over what survived reads as complete. That's the trap. AF-17 · AF-18

BSpawning six subagents, one per area: each writes its map to docs/maps/<area>.md incrementally AS it works, not at the end. If any fails, I report which and what's missing. Synthesis happens from the files.

agent

Five maps complete. The auth subagent died partway, but docs/maps/auth.md holds its first eleven findings, including the entry points. Synthesis is built from all six files, with auth marked partial and its gap named: token refresh flow unmapped. One seam worth noting: core and ingest both claim ownership of the queue schema. Those maps disagree, which is probably the real finding.

you

Rerun just auth's tail, and let's dig into that queue ownership.

correct

Findings on disk incrementally: the failed agent's partial work survives, the failure is disclosed instead of papered over, and the synthesis can even mine the disagreements between maps. Partial files beat perfect memory. AF-17

CFan-out adds coordination overhead. I'll just read the whole codebase myself in one careful sequential pass and write the map as I go.

agent

Map done. Fair warning: the first two areas are mapped in detail; by the fifth, my context was mostly full of earlier code, so ui and billing got one paragraph each, largely inferred from directory names.

you

So the map is deep exactly where I already knew things, and shallow everywhere else.

plausible but wrong

One context can't hold a big codebase: that's not a coordination preference, it's the reason fan-out exists. The sequential pass degrades quietly as the window fills, front-loading detail where reading started. AF-18

Do it by hand

Start at shape 1 on a real question (“how does auth work across these services?”). Move to shape 3 only after shapes 1–2 feel routine, and start with two or three tasks, not a backlog.

Try it with your agent

Map this codebase with a fan-out. Spawn one subagent per top-level
area (cap at six). Each subagent writes a one-page map of its area to
docs/maps/<area>.md AS IT WORKS (files on disk, not chat). Each map:
what the area does, its entry points, what it depends on, one thing
that surprised you. When all return, synthesize docs/maps/OVERVIEW.md
from the files and name the places where two maps disagree or overlap.
Those are the seams that matter. If any subagent fails, report which
and what's missing; don't paper over gaps.

Watch out

Unbounded anything (AF-08): every loop and long-running worker gets a wall-clock timeout, a size cap, and a heartbeat. No exceptions survive contact with a 4-hour wedge.
Queue tasks without acceptance criteria: an autonomous agent with a vague task invents its own definition of done, and you find out at review time.
Merging background work unreviewed: the collection pass IS a review (step 4); autonomy moves the work, never the judgment.