3.2 KiB
Reviewer Gate
The spine's pre-handoff review. Runs at Finalize (after distill + reconcile) and is the Validate intent. The difference is the ending: at Finalize you apply the clear fixes yourself; under Validate you report and don't change the spine.
Cheap deterministic pass first: uv run {skill-root}/scripts/lint_spine.py --workspace {doc_workspace} settles the mechanical misses (placeholders, duplicate AD IDs, missing Binds/Prevents/Rule, unpinned Stack versions), so reviewers spend judgment on the semantic half.
Assemble the menu: a rubric walker that judges the spine against the good-spine checklist below, + every entry in {workflow.finalize_reviewers}, + ad-hoc lenses you invent or offer as the spine's rigor, altitude, and criticality warrant — a security/compliance lens for regulated stakes, a seam reviewer cross-team, a data-integrity lens for a heavy data model. Scale whether and how heavily the gate runs to the stakes: a throwaway prototype may run it quietly or skip the gate entirely; a high-criticality or platform-altitude spine earns more lenses and the explicit all / subset / skip menu. But once the gate runs, the {workflow.finalize_reviewers} always run — they are the configured floor, never cherry-picked out; only the ad-hoc lenses are optional. (Headless never skips the gate.)
Dispatch every entry as a parallel subagent against ARCHITECTURE-SPINE.md (prefix convention: skill: / file: / plain text). Each writes its full review to {doc_workspace}/reviews/review-{slug}.md — a subfolder, so the gate's scratch stays out of the deliverable folder — and returns ONLY a compact summary (verdict, top 2–5 findings, file path) — the parent never holds full review text. An inline self-check does not count: the independent context is the point, because a fresh reviewer finds the divergences the author talks past. If subagents are unavailable, run sequentially — write the file first, then flush it from context.
Good-spine checklist (what the rubric walker judges): it fixes the real divergence points for the level below and misses none; every AD's Rule is enforceable and actually prevents its stated divergence; nothing under Deferred could let two units diverge; named tech is verified-current; it ratifies rather than contradicts a brownfield codebase; if a spec drove it, it covers that spec's capabilities; if a parent spine is inherited, no new AD weakens or contradicts an inherited one; and every dimension the altitude owns is decided, deferred, or an open question — a whole dimension left silent is a finding, especially the operational/environmental envelope (deployment & environments, infra/provider strategy, operations) a domain-focused draft skips.
Surface findings tiered, never dumped: a one-sentence gate verdict, then critical + high; medium/low roll into a tail ("plus N more in {file}"). Per finding: autofix, discuss, defer to Deferred / open items, or ignore. At Finalize this is your own gate — apply the clear fixes rather than handing over a list; surface only what genuinely needs the user. Under the Validate intent, fold every reviewer's output into one bespoke HTML + markdown report and open the HTML.