Review workflow

Flow-Next uses review gates before and after implementation.

Cross-model review is not a Flow-Next invention; people have paired one model against another as a reviewer for a while. What is wired in here is the autonomous adversarial loop: a different model challenges every plan and implementation automatically, at each handover and inside the autonomous modes.

flowchart LR
  Spec["Spec"] --> PlanReview["Plan review"]
  PlanReview --> Work["Work"]
  Work --> ImplReview["Implementation review"]
  ImplReview -->|needs work| Work
  ImplReview -->|ship| Completion["Completion review"]
  Completion --> PR["make-pr"]
  Completion -.optional.-> QA["Live-app QA"]
  QA -.-> PR

The static gates above (plan / impl / completion review) read code and specs. The optional live-app QA stage drives the running app - slot it in after work, around or before make-pr.

Review backends, in one line

Every gate runs through a configurable backend, and the point is that it is a different model than the one that wrote the artifact. Set it once with /flow-next:setup or flowctl config set review.backend <backend>, override per run with --review=, and read the full ladder (rp, codex, copilot, cursor, host, none), the backend:model:effort grammar, and the precedence chain in Review backends.

Implementation reviews also carry an always-on code-smell baseline (Fowler’s Refactoring: Feature Envy, Data Clumps, Primitive Obsession, and the rest) across every backend.

Plan review

/flow-next:plan-review fn-1

Checks whether the spec and plan are complete enough before work begins.

Use it when the work is high risk, cross-module, product-facing, or likely to be delegated. A plan review should catch missing requirements and bad decomposition while the fix is still cheap.

Implementation review

/flow-next:impl-review fn-1

Runs a second model over the diff. Only introduced findings count toward blocking verdicts.

Use a different model or backend than the implementation model when possible. The point is adversarial pressure rather than another pass from the same context. The workflow is a loop: review finds introduced issues, /flow-next:work fixes them, review runs again, and the handoff continues only once the verdict is shippable. What the reviewer is handed, and what it reads for itself, is on Review backends.

The first round draws three reviewers

On the codex and host backends, the first review round of a scope fans out three concurrent draws of the same reviewer, each carrying one axis lens: correctness and logic, contracts and consistency (do docs, tests, and stated promises agree with what the code does), and integration with unchanged code. The coordinator merges the three finding sets into one deduped, ranked set and runs one fix pass over it. Re-review after that fix is a single dispatch carrying the whole merged set, because re-review verifies fixes and that needs continuity rather than breadth. The merged round counts as one round against the review cap, not three, and the receipt records each draw.

Pre-registered evals are what set the shape: a single review pass surfaced roughly 45% of the validated finding pool, while the union of three axis-differentiated draws reached 1.56x single-draw recall against a pre-registered 1.5x bar, at flat validity. What used to trickle out over several serial rounds mostly arrives in the first merged round instead.

Two bounds stay true. A clean one-round diff pays roughly 3x review tokens for findings one draw would have surfaced anyway, and roughly a third of validated findings eluded every draw, so round 2 shrinks rather than disappears. Both are steerable in a sentence rather than a setting - see Steering the fan-out for the economy and cross-family phrasings. rp, copilot, and cursor keep a single dispatch every round, and completion review, land, and external PR bots are unchanged.

Completion review

/flow-next:spec-completion-review fn-1

Checks the combined implementation against the whole spec after all tasks are done.

This is different from implementation review. Implementation review checks a diff. Completion review checks whether the full spec is satisfied after all tasks, merges, and fix loops.

Live-app QA (optional)

/flow-next:qa fn-1

Every gate above is static - it reads code or specs. QA is the live-app gate: it drives the running app like a real user, derives scenarios straight from the spec (AC, R-IDs, boundaries), files P0/P1/P2 findings with evidence, and emits a YES/NO qa_verdict receipt that can feed completion review.

Opt-in - it needs a live deploy + a driver (Flow-Next Drive); with neither it surfaces a BLOCKED verdict rather than failing, and adds nothing to the base flow when unused. It is forbidden from marking PASS by reading source.

PR review

/flow-next:make-pr fn-1
/flow-next:resolve-pr 123

The PR body summarizes acceptance coverage, critical files, decisions, memory, deferred findings, and review focus.

With the opt-in HTML artifact mode (2.0.0+), make-pr also emits a PR render lens - a self-contained, diff-derived HTML review instrument with a churn map grouped by review intent, an R-ID → evidence table verified against the spec export, and a where-to-look checklist. Read-only by design: PR feedback stays in review threads.

When a review finds something

One table, whatever raised the finding. The rule underneath it: fix the artifact that caused the gap, and put the fix back into .flow/ rather than leaving it in the chat transcript.

Signal	Response
Plan review finds unclear product behavior	Rerun /flow-next:interview --scope=business
Plan review finds technical gaps	Rerun /flow-next:interview --scope=technical with repo and docs context
Impl review finds an introduced bug	Rerun /flow-next:work on the affected task
Impl review flags an architectural mismatch	Revisit the spec’s decision context
Completion review finds uncovered acceptance criteria	Add or repair task coverage, or rerun /flow-next:plan
Live-app QA files a P0/P1 (or a BLOCKED/NA verdict)	File the finding to the bug track, add a fix task, or supply the missing deploy or driver
A review false positive keeps returning	Record the suppression with evidence, or add validator evidence
The same receipt finding returns unaddressed	Address it, suppress it with evidence, or defer it visibly in the PR body
The planner invented architecture	Rerun the technical interview with repo and docs context
A worker changed unrelated modules	Split the task or add dependencies
A human reviewer is confused	Improve task summaries, then regenerate the PR body

Review is part of the workflow, not an afterthought at the end.