Worked examples

Five fan-outs. Each adds a rule the others do not — and the last one is where you should not fan out at all.

These assume the principles in delegating to agents: verify by running, keep cross-slice work yourself, treat a done as a claim.

1. Triaging a Sentry backlog

Adds: the grouping is yours, and “diagnose it” is not a done condition.

• Group the unresolved Sentry issues by root cause and put a worker on each group.

• Group inline, always. A worker sees one slice and cannot tell that its stack trace and someone else's are the same bug. Sentry's fingerprinting is a starting point — it splits one root cause across several issues routinely.
• Convert each group into a finish line. A failing test named for the issue, plus a patch that turns it green. An explanation of what is probably wrong is not a done condition.
• Check file overlap first. Two groups fixing the same file are one worker's job.
• Brief inline: issue text, why you grouped them, the done condition, the command that proves it.
• The merge back is yours. Six branches that each pass alone can still fail together.

When a gate releases, run the test rather than reading the diff:

git fetch && git checkout <branch>
go test -run TestIssue4412 -count=1 ./...      # green
git stash && go test -run TestIssue4412 ./...  # red without the patch

Red without the fix, green with it — or it is a test that passes for unrelated reasons, which is how this slice usually fails.

2. Burning down an issue backlog

Adds: the slices already exist, so the work is grooming and order.

• Groom before dispatch. An issue with no stated done condition is not a slice. Rewrite it or keep it.
• Order by dependency, not issue number. If #14 builds on #12's refactor, that is two waves — never two concurrent workers.
• Waves of three to five. Workers are parallel; your gate-and-verify cycle is not, and it is the bottleneck.
• One pull request per issue. A worker landing two on one branch has removed your ability to revert one.
• Verify against the issue's own condition, not “the suite is green” — a green suite is compatible with the issue being untouched.

3. A wide mechanical change

Adds: this is where isolation actually earns its cost.

Renaming an API across forty call sites. Bumping a dependency across every package. Shallow, wide, and genuinely conflict-prone — the writers overlap by nature.

• Batch by module, never by call site. Forty workers is forty briefs and forty gates for work one pass would finish.
• Then count. A passing build is compatible with a worker having deleted the call site rather than updated it.
• Keep the last sweep. The final few sites are generated code, string literals and docs — judgement, not a slice.

go build ./... && go test -count=1 ./...
grep -rn "oldName" --include="*.go" . | wc -l   # expect 0
grep -rn "newName" --include="*.go" . | wc -l   # expect ~40

4. Hunting a flaky test

Adds: some done conditions need repetition, or they prove nothing.

• Require a deterministic reproduction first. A worker that cannot make the test fail on demand has not found the flake, however good the theory sounds.
• Put repetition in the done condition — go test -run TestThing -count=200 ./... — and run it yourself after the gate. Your two hundred passes and the worker's are different evidence.
• One worker per flake, not per file. Two flakes in one file are usually one race.

5. When not to fan out at all

Adds: the cost is real, and three common jobs do not repay it.

• Read-only sweeps. An audit, a dependency review, “where is this used”. Nothing will be written, so there is nothing to isolate.
• Work whose output is a judgement. No command settles “is this architecture right?”, so verification collapses and you are back to reading everything.
• Anything one writer can finish. Isolation exists to stop concurrent writers colliding.

The test: can you name the command that proves it is done, and will more than one agent write files at the same time? Two yeses is a fan-out. Anything less is a subagent, or just you.