Sectioned fan-out with synthesis

---
name: sectioned-fan-out
description: Split a task with several independent parts into bounded sections, run one agent per section in parallel, and merge their reports in a mandatory synthesis pass. Use it when a review, audit, build or research task has two or more parts that do not depend on each other's output.
---

# Sectioned fan-out with synthesis

One agent working a task with five independent parts spreads one attention budget across all of them.
Nothing forces the fifth part to get the attention the first one got, and you never learn what it skipped.
This workflow gives each part its own agent with a hard boundary, makes every agent report what it
actually covered, and closes with a synthesis pass that turns every uncovered spot into a visible finding.

Read `CONTEXT.md` next to this file before you start. It holds the reader's model tiers, concurrency cap,
report folder and any project-specific seams.

If `CONTEXT.md` is missing, or a field you need is blank, stop and ask the user for it in the user's
language before you dispatch anything. Ask for one field at a time and name what it is for, for example:
EN "Add your concurrency cap: how many section agents may run at once on your machine?",
PL „Podaj limit równoległości: ilu agentów sekcji może działać naraz na Twoim komputerze?”.
Write the answer into `CONTEXT.md` so you do not ask again.

## Before you start / What you need

- **An AI coding agent that runs subagents in parallel** (required). Any of these works:
  - Claude Code: install from https://code.claude.com/docs/en/setup, subagents at https://code.claude.com/docs/en/sub-agents
  - Codex CLI: install from https://developers.openai.com/codex/cli, subagents at https://developers.openai.com/codex/subagents
  - Cursor: install from https://cursor.com/downloads, subagents at https://cursor.com/docs/agent/subagents

  Test it once: ask for two subagents that each list one folder, and check that both started before the
  first one replied. If they run one after another, this workflow loses its point in your tool.
- **A report folder** the section agents can write to, named in `CONTEXT.md`.
- **A token budget** for several parallel contexts. Every section loads its own.

## 1. Decide whether to fan out

Fan out when you can name two or more chunks of the task that do not need each other's output.

Do NOT fan out when:

- **The task is trivial.** A single command, a one-line edit, a status lookup. Do it directly.
- **The work is indivisible.** One small surface with no independent seams gets one agent.
- **The steps are strictly sequential.** If each step needs the previous step's output, you have a pipeline, not a
  fan-out. Run it in order.
- **The task is short.** Every section agent loads its own context, so a fan-out costs several times the
  tokens of a single agent. It pays off on long, wide tasks and wastes budget on quick ones.

If none of these hold, fan out.

## 2. Cut along seams

List the sections before you dispatch anything. Pick the seam that matches the task:

| Seam | Cut by | Example |
|---|---|---|
| File or module | directory, package, file group | `checkout/`, `catalog/`, `accounts/` in a small online shop |
| Domain or subsystem | frontend, API, billing, auth, webhooks, migrations | one agent per subsystem of a small web app |
| Source | repos, documents, datasets, research angles | three competitor sites, two forums, one changelog |
| Concern | correctness, security, performance, data integrity, UX | four reviewers over the same diff |
| Feature slice | one feature end to end | "invite a teammate", "export invoices" |

For every section, write its boundary in one line: the exact files, folders, domain or question it owns.

**Keep boundaries disjoint.** Two agents editing the same file will overwrite each other. If a shared file
cannot be avoided, give exactly one section write access and make the others read-only on it.

### Connective tissue: the seams between the seams

Cutting by resource leaves the connections between resources unowned, so every section can report
green while the feature as a whole does not work.

- **User-facing work: cut by user journey.** A section is a path a person walks end to end ("reset a password and
  log back in", "place an order and get the confirmation email"), through however many resources
  it crosses.
- **If you must cut by resource, name the owner of every seam.** Write into the dispatch which section
  owns each page, handler or file that sits between two sections. An unnamed seam is an unowned seam.
- **Resource-complete is not working.** A section can honestly finish its files while the feature stays
  unusable. Each section verifies its own slice end to end before it reports green. For UI work that means
  driving the real interface, not calling an endpoint and trusting the response.

## 3. Set concurrency and model tier

- **Concurrency:** read the cap from `CONTEXT.md`. If there are more sections than the cap allows, run them
  in waves, each wave in one message. If the machine is short on memory, lower the cap before you start;
  running out of memory mid-fan-out loses every section's work.
- **Model tier per section:** use the cheap tier from `CONTEXT.md` for mechanical sections (clear spec,
  no judgment: renames, log extraction, checklist sweeps). Use the strongest tier for sections that need
  judgment (architecture, security, taste, adversarial review). If a cheap-tier section returns weak work,
  rerun it on a stronger tier if the "Escalation allowed" field in `CONTEXT.md` says yes, otherwise ask the human first.

## 4. Dispatch every section in ONE message

Send all section agents of a wave in a single message with multiple agent calls. Calls in one message run
in parallel. Calls spread over separate messages run one after another, and you lose the whole gain.

Every section prompt states four things: the boundary, the task, the exact output shape, and the stop
point. Use this shape:

```
You are the section agent for: [section name].

BOUNDARY: you work ONLY on [files / folders / domain / journey].
Nothing outside this boundary. If you see a problem next door, record it
as a cross-section dependency. Do not fix it.
[If this section owns a seam: you also own [seam]. Verify it end to end.]

TASK: [what to find, check or build]

Return exactly this (shape in section-report.template.md):
1. Coverage map: every file, flow or source you actually opened or exercised.
   Anything not on this list counts as unchecked.
2. Findings: each with severity (CRITICAL / MAJOR / MINOR) and location.
3. Cross-section dependencies: anything in your section that touches another.
4. Verification: how you proved your slice works end to end.

REPLY CONTRACT: write the full report to [report folder]/[section-name].md.
Reply to me with ONLY the file path and a summary of at most [summary limit
from CONTEXT.md], written for a reader
who has seen none of your work: outcome first, then anything I must decide
or reconcile, in complete sentences. Do not paste the report into the reply.

STOP: finish after the report is written. Do not widen the scope.
```

## 5. Keep working while sections run

Dispatching is not a reason to stop. While the sections run:

- Do the parts that depend on nothing: read the seams yourself, prepare the synthesis frame (an empty
  combined coverage map listing every surface of the task).
- Answer questions sections send back, from the original task and its constraints.
- Intervene in a section that has gone off track or lacks context it needed. Correct it, or stop it and
  redispatch with a better prompt. Do not wait to discover the problem at synthesis.

## 6. The context-safety contract

Large reports stay on disk. A section that pastes its full report into its reply can overflow your
context mid-synthesis, and then all section work is lost. The rule for every section, with no exceptions:

- Substantial, durable or large output goes to a file in the report folder from `CONTEXT.md`.
- The reply is the path plus a short, selective summary: outcome first, then what the parent must decide.
- You read from each file only the part you need at the moment.

Keep the summary length limit from `CONTEXT.md` in every section prompt.

## 7. Gate each report

A section report fails, and gets redispatched with a corrected prompt, when:

- it has no coverage map,
- a finding has no severity or no location,
- the section claims green without saying how it verified end to end,
- the full report came back in the reply instead of in a file.

## 8. Synthesis pass (mandatory)

Never hand back N separate reports. Merge them into one result:

1. **Combine the coverage maps** into one map against the full task surface you listed in step 5.
2. **Name every uncovered spot.** A file, flow, domain or seam that appears on no map is a finding in its
   own right. Dispatch a follow-up agent for it. The task is not closed while a blank spot remains.
3. **Walk the cross-section dependencies.** Each one either lands on a section that covered it, or it
   becomes an uncovered seam under point 2.
4. **Reconcile conflicts.** When two sections disagree, decide which one is right and write why. Never
   drop a finding silently.
5. **Order findings by severity**, not by the order reports arrived.

Return: the combined coverage map, the list of blank spots with the follow-up dispatched for each, the
reconciled conflicts, and the top actions in order.

Synthesis prompt, if a separate agent does it:

```
You have [N] section reports: [paths]. The full task surface is: [surface list].

1. Merge the coverage maps into one. List explicitly what NO section covered.
2. Check every cross-section dependency against the merged map.
3. Resolve conflicting findings and state why. Do not delete any silently.
4. Sort findings by severity, not by the sequence reports came in.
5. Return: merged coverage map, blank spots, resolved conflicts,
   top actions in order. Write the full result to [path]; reply with path + summary.
```

## Failure modes

| Symptom | Cause | Fix |
|---|---|---|
| Parent context overflows during synthesis | sections pasted full reports into replies | reply contract in every prompt; reports on disk |
| Two agents overwrite the same file | overlapping boundaries | disjoint boundaries, or one writer and the rest read-only |
| Every section green, feature broken | sections cut by resource, seams unowned | cut by user journey, or name each seam's owner |
| A part of the task was never checked | no coverage map, or no synthesis | coverage map is mandatory; synthesis lists blank spots |
| Sections ran one by one | dispatched across several messages | one message per wave |
| Machine stalls or kills agents | too many sections at once | respect the concurrency cap; run waves |