Skip to content

Bounded Reviewer Dispatch (SPEC-145 US-3, Decision 5 / AD-4)

How /vt-c-4-review dispatches the reviewer set chosen by persona-catalog.md / persona-select.sh — so latency and context scale with the diff, and an extended reviewer set (or ultracode mode) never fails on a concurrency ceiling.

The bound

MAX_CONCURRENT = 8

A fixed number, stated explicitly so test-persona-selection.sh can assert it. Rejected alternatives: a host-dynamic min(16, cores-2) (non-deterministic in tests) and a settings-configurable key (deferred — a vt_review_max_concurrent setting can be added later if a real need appears). At most 8 reviewer subagents run at once.

Raised from 4 to 8 on 2026-07-03 per SPEC-145 review PERF-1: the measured selection is 6 reviewers for a common TS/JS code review (floor 2 + code-core 3 + language 1) and 9 for an unknown-diff or frontend-heavy review (floor 2 + code-core 3 + language 1 + julik + accessibility + design/data-integrity). At 4, a common review takes 2 waves and the worst case takes 3; at 8, the common case fits in one wave and the worst case in two — halving wall-clock without loosening the retry-on-capacity safety net. Determinism is preserved by asserting a constant (whatever the number), not specifically 4 (see Decision 5 amendment in decisions.md).

Queue + retry semantics

  1. Compute the selected reviewer set (floor ∪ diff-triggers ∪ type-reviewers).
  2. Dispatch the first MAX_CONCURRENT reviewers in parallel.
  3. Hold the remainder in a FIFO queue; as each running reviewer returns, pull the next queued reviewer and dispatch it. Order is deterministic (the sorted selection order) so behavior is reproducible.
  4. On a capacity error from the host (too many concurrent subagents), retry with backoff — do not hard-fail. The reviewer goes back on the queue and is re-dispatched when a slot frees. Backoff is exponential with a small cap; a reviewer that repeatedly cannot be scheduled is reported as deferred in the review output, never silently dropped.

Capacity errors are a scheduling condition, not a review failure: the fixed bound plus retry-on-capacity is what lets the selection grow (ultracode, extra personas) without race failures.

Why this pairs with selection

Selection decides who reviews; bounded dispatch decides how many at once. Together they deliver the US-3 goal: the median reviewer count drops from a fixed 6 to a diff-scoped 3–4 (selection), and whatever the count, dispatch never exceeds 8 concurrent nor fails on capacity (bound + retry). Neither half drops a selected reviewer — a queued or retried reviewer still runs; it just runs later.