The Field Manual

The Multiplied Mistake

Part III: Your Own Hand

You are here if

You are about to run one command against sixty targets. A sweep, a bulk commit, a scripted reconciliation, a find-and-replace across everything the glob can reach. Or you are halfway through one, the outputs scrolling past uniform and green, and the uniformity itself has started to bother you.

You are here if the word all is in the command: all dirty repos, all branches, the full portfolio, whatever the wildcard finds. You are here if you tested the operation on one item, it worked, and the plan for the other fifty-nine is the same command with a longer list. You are here if one project changed and the tool in your hand reprocesses every project it knows about. You are here if you are sizing a migration and the honest answer to how many places does this touch is a guess. And you are here afterward, when a batch reported clean and one item out of dozens turns out to have been nothing like the others.

If a single mutation misfired once, at width one, this is not your chapter; what happened next decides which is. If the one thing it did cannot be undone, that is chapter 10. If someone else ran the work and what you hold is their account of it, that is chapter 6. What lands you here is width, not the clock: you can arrive before your own hand multiplies something, or after a wide run came back uniformly green and one item turns out not to have fit, and it is the same chapter either way.

The mechanism

A batch operation is one assumption executed N times. The assumption rides along invisibly because every batch is written against an imagined population: sixty repos that are all the same repo, sixty files that are all the same file. No real population is that uniform. Each repo has its own default branch, its own drift, its own kind of dirt; each file has its own edge of the regex. The batch applies one model of the item to every item, and the items that do not fit the model do not refuse the operation. They absorb it wrongly and report the same green as the rest.

Scale then defeats exactly the checks that catch a single mistake. When you run one mutation, you look at the result, and that look is the verification. When you run sixty, you look at the first three and at the scroll rate of the rest. Sampling verifies the procedure, not the population, and the item that breaks is by definition not the typical member your sample drew. The wildcard removes even the denominator: with a glob or an all flag, the list of what the operation touches is assembled by the machine at execution time, so you never see it, and afterward there is no count to reconcile the results against.

The type specimen. A documentation sweep across dozens of repositories carried three assumptions, each of them ordinary, each survivable once. It assumed every repo's default branch shared one name; some did not. It assumed each local base was current; one had drifted stale enough that merging it blind would have deleted live content, and only a pre-merge check against the remote caught it. And its merge step went through the platform's server side, a path the push-to-main guard never sees, so the one control installed against exactly this class of damage watched none of it happen. On a normal day any one of these is a bug, found in a minute, fixed in five. The sweep ran each of them dozens of times. That is this chapter's whole claim: a wrong assumption is a bug, and the same wrong assumption times sixty repos is an incident, and the difference between the two is not more caution. It is a different procedure.

Scale also breaks the machinery around the batch, not only the items inside it. The synthesis step that any single result would pass through cleanly times out on the concatenation of sixty. The fan-out sized to the work rather than to the platform's concurrency cap becomes a rate-limit incident before the first item lands. Book One builds the verification loop one artifact at a time; this chapter is that loop under multiplication, where the operation has sixty targets and your attention still has one.

The discipline

Pilot on one, bucket before batch, and scope every mutation to an enumerated list; never let a wildcard decide what the operation touches.

The ritual:

  1. Enumerate before you write the command. Produce the literal list of targets first, as an artifact the command consumes, not a pattern the command expands. If the tool only operates on everything, set the changed values directly instead of re-running the tool. Pass: a written list exists, you know its length, and no wildcard survives into the mutating command.
  1. Bucket the list. Walk the enumeration and label what each item actually is, because the batch was written for one kind and the list contains several: real edits, formatter churn, deletions that only look like churn; repos on the assumed branch and repos not. An item you cannot classify leaves the batch. Pass: every item carries a label, and the operation runs on exactly one bucket.
  1. Pilot on one, end to end. Pick the worst plausible candidate, not the easiest, and run the entire procedure on it, through verification against the authoritative source. The pilot also prices the whole job: if the one item reveals the work is deeper than the estimate, multiply the estimate before continuing, or narrow the scope to one boundary at a time. Pass: one item is fully done and independently verified before item two begins.
  1. Keep ordered mutations in one pair of hands. If any step depends on another having finished, on a shared base merging first, on a guard seeing calls in sequence, the operation runs inline and sequentially. Fan out discovery and scoring; never fan out sequenced writes, because the workers do not share your sequencing awareness. Pass: either you can state that the items are order-independent, or nothing about the run is parallel.
  1. Isolate the fallible. Destructive, token-gated, and fallible calls run alone. Bundled into a parallel batch, one nonzero exit cancels innocent siblings and one extra command voids a one-time token. Pass: everything sharing a parallel bundle is independent, safe to fail, and cheap to rerun.
  1. Verify per item and reconcile the count. After the run, a mechanical check visits every item, not a sample, and reads the authoritative source, not the tool's exit banner: grep for zero remaining conflict markers, ask the platform whether the merge actually landed, diff what changed on the items that reported nothing. Then compare the pass count to the enumeration from step 1. Pass: checks passed equals list length, and any shortfall names its items.

The case ledger

Eleven entries. Nine are single assumptions that became incidents by multiplication; two, E024 and E025, are the batch breaking the machinery around itself.

[E024] Large agent fan-out hits provider rate limits (undated) Receipt: a fan-out of dozens of parallel agents queued past the platform's concurrency cap and hit provider rate limits. Rule: for large pure-shell scans needing no reasoning, prefer a direct concurrent subprocess pool over a big agent fan-out; reserve agent fan-out for tasks that need judgment.

[E025] Synthesis step times out on an oversized inlined prompt (undated) Receipt: a workflow's final synthesis step timed out when tens of kilobytes of prior results were inlined directly into its prompt. Rule: don't inline large structured results into a synthesis prompt; synthesize in the main context after the run completes, recovering results from transcripts if needed.

[E037] Fallible or token-gated commands break a parallel batch (2026-05-30) Receipt: batching a fallible or one-time-token-gated shell command together with parallel read and edit calls let one nonzero exit cancel the whole batch, and bundling extra commands voided the token. Rule: isolate destructive or token-gated commands, and any fallible observational command, from parallel batches; batch only independent, safe calls together.

[E038] Multi-repo sweeps amplify small per-repo assumptions (2026-05-18 to 2026-06-14) Receipt: a documentation sweep across dozens of repos hit wrong default-branch assumptions, stale-base resets, and a server-side merge path that bypassed the push-to-main guard; one repo's stale base would have deleted live content if merged blind. Rule: verify each repo's real default branch and fetch before resetting, verify a no-loss invariant against the current remote (not a local backup) before every merge, and never treat a server-side merge command as a safe dodge of a push-to-main guard.

[E039] Multi-branch integration needs a specific merge order (2026-06-20) Receipt: consolidating several parallel feature branches onto trunk in one pass required merging the shared base first, or the build broke and generated files re-diverged. Rule: integrate multiple branches in an isolated workspace, merge the shared base first, regenerate (don't hand-merge) generated files, then run the full verification gate once before landing.

[E041] Scripted reconciliations drift against a moving remote (2026-06-02) Receipt: a scripted multi-repo documentation reconciliation computed each merge against a local head that had already drifted from the remote, causing cherry-pick conflicts on re-sweep. Rule: script multi-repo landings deterministically, pilot on one repo first, and confirm a merge actually landed by checking the platform API's real state, not a local shell's cosmetic warning.

[E047] Bulk dirty-repo commits can hide real deletions (2026-06-26 / 2026-07-03) Receipt: a bulk commit-all-dirty-repos pass nearly committed over working-tree deletions of tracked source files, indistinguishable at a glance from harmless formatter whitespace churn. Rule: inspect and bucket every dirty repo in a batch (real edits vs. formatter churn vs. actual deletions) before committing anything; restore deletions path-scoped, never blanket-add.

[E084] Ordered mutations don't belong in a large parallel fan-out (2026-05-30) Receipt: fanning out an ordered, guard-sensitive set of mutations across many parallel workflow agents added latency and race risk for no benefit, since those agents don't share the lead's sequencing awareness. Rule: use large parallel fan-out for discovery and scoring work, but execute ordered, guard-sensitive mutations inline, and always run a deterministic pre-flight check before any large fan-out.

[E085] Full shared-pipeline commands overreach a single-project change (undated) Receipt: running a full-portfolio batch command to push one new project through a shared pipeline would have reprocessed dozens of unrelated projects and reset properties already correctly set. Rule: when pushing one project through a shared multi-project pipeline, set only the values that changed directly rather than re-running the full-portfolio command.

[E106] Async migrations routinely understate their own scope (2026-05-17 / 2026-05-18) Receipt: an everything-async migration across a codebase with existing type casts and loosely-typed helpers routinely understated its own scope, because the type checker can't see promise leaks through casts and generic assertions. Rule: before committing to scope on a broad async migration, grep for cast and any-type density as a scope predictor, multiply the naive estimate, and prefer narrow boundary-by-boundary migrations over one sweeping change.

[E153] A cross-line regex silently merges separate lines (undated) Receipt: a bulk find-and-replace script meant to strip a punctuation character used a regex that could cross line boundaries, silently merging separate lines together while the character count still looked correct. Rule: run bulk text-scrubbing line by line, never with a regex that can match across a newline, and grep for merge artifacts afterward.

Adjacent doors

If any item in the batch is a one-way door, a delete, a publish, a drop of anything unrecoverable, then multiplication is not the leading hazard, irreversibility is, and the pilot stops protecting you: piloting a publish on one item publishes one item. The two disciplines nest rather than simply queue. Step 1 here, the enumerated list, runs first regardless, because chapter 10 cannot check what is behind sixty doors until you have named the sixty. Then chapter 10's per-item enumeration runs on that list, and this chapter's pilot and the steps after it run on whatever survives. Where the two meet at the door, chapter 10 carries the precedence: the door outranks the count, because a one-way door removes exactly the cheap-to-fail pilot this chapter's safety rests on.

If delegates ran the batch and what you hold is their reports, step 6 has not happened yet, whatever the reports say. Sixty claims of done are sixty claims, and the discipline for reading a worker's account of its own work is chapter 6's. Come back here with the bytes.

If your list has three items on it, you have not crossed into scale, and chapter 11 owns the call on how much of this ceremony three items deserve. The procedure above is priced for a population too large to hold in your head. At three, the enumeration is your head, the pilot is a third of the run, and the honest version of this chapter is to do them one at a time with your eyes open, which at that size is not a discipline. It is just the work.