Spec Completion Review

/flow-next:spec-completion-review confirms that, taken together, the implementations of every task in a spec actually satisfy the acceptance criteria.

This is not a code-quality review. That belongs to /flow-next:impl-review. Completion review answers one question: did the combined work meet the spec?

When to use it

Run completion-review when every task in a spec is marked done, after any per-task /flow-next:impl-review has shipped, and before /flow-next:make-pr opens the PR. The reviewer re-reads the spec and verifies that the combined diff covers every R-ID - gaps that no individual task fully owned surface here.

Specifically:

• Long-running spec where individual tasks were reviewed in isolation but no one checked the whole.
• Spec where task descriptions drifted away from the original acceptance criteria during execution.
• Any non-trivial spec before opening a PR for human review.

The work loop runs this automatically when all tasks of a multi-task spec complete. A spec with a single task skips it: once that task’s review reaches SHIP (or a recorded override), work marks completion review not_required and the stage line says so, since the per-task review already covered the whole spec. You can also invoke it manually at any time, including on a single-task spec.

Which diff it reviews

Completion review judges the spec’s own changes: the diff from where its branch left its base. With --base, that is the branch you name. Otherwise it is the branch work started the spec from (a release integration branch, a goal/ branch, or the branch you passed to /flow-next:work --base), then the parent spec’s branch for a chained spec, then your default branch. Work records its base in .flow/tmp/, so a review you run by hand in a fresh checkout falls back to the parent spec or the default branch; pass --base there.

What gets checked

• Every R-ID in the spec maps to evidence in the diff or the committed code.
• No acceptance criterion is missing, half-implemented, or quietly dropped.
• Boundaries and non-goals are respected.
• Decisions captured during implementation are consistent with the spec’s decision context.

If an R-ID has no evidence, the review surfaces it as a gap - not as a stylistic finding.

Standing criteria compliance

When the project has a .flow/criteria.md, completion review is also the surface that judges it. Every G-ID in that file is judged against the whole implementation, on every backend, and each gets one status: met, violated, or n/a.

The verdicts land in the ordinary review receipt:

"criteria": [
  {"id": "G1", "status": "met"},
  {"id": "G3", "status": "violated", "note": "route added without contract regen"}
]

Every violation is also reported as a normal finding at reviewer-judged severity, so the findings list stays the one place to read detail. Per-task /flow-next:impl-review never judges criteria: the spec is the unit of compliance.

An invalid criteria file fails the review before a round is reserved (flowctl criteria prompt-block exits nonzero), so a typo’d bullet is a fix-and-re-run, not a silently rule-less review. No criteria file means no criteria content in the prompt and no criteria field in the receipt.

Full model: Standing Criteria.

Backend selection

Same resolution as the other review skills; the ladder is in Review backends.

With review.backend none this skill exits cleanly instead of running, which means nothing verifies R-ID coverage at the end of the spec. The in-host quality audit inside work is not a substitute: it reviews the diff when a change is large or risky, and it never walks the R-ID table. To keep this gate without a second CLI, use host.

Outcomes

Verdict	Meaning
SHIP	Every R-ID covered. Safe to PR.
NEEDS_WORK	One or more R-IDs missing or under-delivered. Findings cite the R-ID and the gap.

A NEEDS_WORK verdict often means a new task, not a rewrite. Use /flow-next:plan or flowctl task create to add the missing work, then re-run.

Why a separate skill

A per-task review can confidently SHIP a task that delivered exactly what its description asked for, even when the task description itself missed something the spec required. Completion review re-grounds on the spec, not on the task list, so spec-level gaps stop hiding behind passing task reviews.

Worked example

/flow-next:spec-completion-review fn-12-export-json-flag

Spec-level review (cross-model): does the sum of tasks implement the spec?
  R1 export --json emits valid JSON      covered (task .1, commit a1b2c3d)
  R2 null-owner rows serialize           covered (task .1 fix round, commit f7c8d9e)
  R3 docs + tests                        covered (task .2, commit e4f5a6b)
No drift found between task done-summaries and the diff. VERDICT: SHIP

Task-level reviews check each tree; this gate checks the forest - drift hides in the gaps between tasks.

Tips

• Run it when all tasks are done and before the PR - it is the last moment where a missed criterion is a task, not a review comment.
• The classic catch: two tasks each “done” correctly that together still miss an R-ID both assumed the other covered.
• Work runs this gate automatically on multi-task specs, attended or not; on a single-task spec it is your call, priced at one review for whole-spec confidence.

Dynamic usage

Recipes that compose with spec-completion-review in the cookbook:

• Evidence-first - the R-ID-to-commit mapping it verifies is the same one the PR body will publish.
• One-shot chains - chain it between “work” and “make the PR” in a single instruction.

Next step

/flow-next:make-pr <spec-id>