parallelize-batch-work

Parallelize Batch Work — Fan Out, Don’t Sequence

Trigger: ≥2 independent units. Not a size threshold — two independent units already justify fanning out; the pre-flight below is the operative check. Under-spawning is the costlier failure: a sequential run that could have been parallel burns wall-clock invisibly, while an over-spawn is refused on the spot by a blocking guard.

Independence check (gates the trigger): fan-out only when units are independent — no shared mutable state, no sequential dependency, no shared design-intent; otherwise partition into an independent DAG or treat as coupled. The token-multiplier cost gate applies to AI-subagent fan-out only; script/process parallelism stays aggressive.

Rule

The AI-subagent fan-out arm assumes the Agent/Task tool is available this session — when features.agentFanOut: false is set in t1k-config-core.json, or a session-level instruction has disabled the tool, that arm is unsatisfiable and script/process parallelism is what survives; say so rather than silently sequencing with no disclosure. Default true.

When you find yourself about to write a sequential loop over a batch (subagent processing 300 items one-by-one, for url in list; do ...; done, single-threaded HTTP loops), STOP and pick a parallel strategy from the strategy table in docs/parallelize-batch-work.md.

Pre-flight (≥2 independent units): before sequencing ANY multi-step op, count independent units (distinct repos/files/PRs/tasks). If count ≥ 2, state your decision in one line: “parallelizing N units” or “sequencing because [dependency]”. Default bias = parallelize; sequencing requires a stated reason.

Read-only fan-out widens freely to the cap. Write-capable fan-out needs isolation FIRST — parallel sub-agents on the SAME repo share one working tree and silently clobber each other’s edits with no conflict marker; give each lane its own git worktree add (parallel-teammate-git-index-race.md) or sequence within one sub-agent. Different repos are always safe.

Full details

docs/parallelize-batch-work.md (strategy table, concurrency degrees, independence test, anti-patterns) · preview-first-batch.md (smoke-test gate) · always-ask-on-unresolved.md (concurrency-degree decisions).