Task: Generate SPECREVIEW.md — Per-Unit Specification Gate

Task: Generate SPEC_REVIEW.md — Per-Unit Specification Gate

Objective

Produce a SPEC_REVIEW.md that serves as the mandatory gate between G1 (/SPEC.md) and G4 (/PLAN.md) of the Agent-Driven Development per-unit pipeline. It validates a single unit's SPEC against the contract declared in the trigger artifact(s) (roadmap/<NNN>-<slug>/ROADMAP.md or issues/<NNN>-<slug>/ISSUE.md), against the design suite the unit cites, against every related unit's SPEC, and against the existing codebase, then catalogues every finding under stable SF-NN / CF-NN / QF-NN / R-NN IDs with severity, evidence, and a proposed actionable edit, and emits a machine-readable verdict (pass, fix-required, or prototype-needed) that the orchestrator branches on. An agent reading this document alone can — without re-opening the SPEC, the design read-set, or any related-unit SPEC — tell whether the pipeline may proceed to PLAN, must regenerate the SPEC with this review as additional input, or must first run the conditional G3 PROTOTYPE step to empirically validate risky assumptions.

SPEC_REVIEW.md exists because every other ADD review gate catches a different category of failure — DESIGN_REVIEW catches cross-artifact contradictions in the design suite, CODE_REVIEW catches issues in implementation — but the SPEC itself, the one consequential intermediate artifact between design and code, had no review gate. Real-world testing of the pipeline surfaced five recurring failure modes the SPEC author silently propagates downstream: scope drift (the SPEC implements less than the unit definition calls for), premature deferral (the SPEC defers work to "future units" or to PLAN/IMPLEMENT that has no actual home elsewhere), reinvention (the SPEC prescribes custom logic where a well-known open-source library already solves the problem), convention drift (the SPEC prescribes a filename, package shape, or naming pattern that contradicts framework documentation or existing monorepo packages), and empirical gambles (the SPEC makes implementation decisions that depend on unverified assumptions about library behavior, runtime semantics, or external system shapes). The defining discipline — and the commonest violation — is that the verdict field follows blocking_findings and risk_items mechanically with no subjective override. A reviewer who believes a blocking finding is acceptable downgrades the finding's severity, with justification, rather than overrides the verdict. A reviewer who is uncertain whether an assumption is empirical or document-verifiable resolves the question in Phase 1 — not by inflating R-NN.

Inputs

1. Trigger artifact(s) (required) — one or more roadmap/<NNN>-<slug>/ROADMAP.md (planned work) and/or issues/<NNN>-<slug>/ISSUE.md (defects in shipped code) that initiated this unit. These declare what the unit must deliver, its acceptance criteria, and its area. Combined with the unit's SPEC frontmatter (declared by the orchestrator: area, files, concepts, depends_on, supersedes, related), they form the contract the SPEC must satisfy. Every SF-NN finding anchors to a verbatim quote of a requirement from the trigger body or a frontmatter scope element.
2. SPEC.md (required, primary subject) — the document being reviewed. Path is units/<area>/u<NN>/SPEC.md. Read end-to-end, including frontmatter.
3. The unit's declared design read-set (required) — the design artifacts the SPEC was supposed to cite, supplied by the orchestrator at invocation time per the unit's scope. Subset of DOMAIN, ARCHITECTURE, INTERFACES, DATA, BEHAVIOR, ERRORS, QUALITY, SECURITY, USE_CASES, surface IAs. Used both for citation validation (every INV-NN, EP-name, EVT-name, ERR_CODE, SM-*, SAGA-*, METRIC-*, SLO-*, THREAT-NN, MIT-NN, UC-NN, D-NNN cited by the SPEC must resolve in the corresponding registry) and for cross-checking that the SPEC's claims are consistent with the design.
4. Related unit SPEC.md files (required, supplied by orchestrator) — the SPECs of units this unit depends on, supersedes, or is otherwise related to (orchestrator-discovered via the unit's frontmatter depends_on / supersedes / related plus area peers in units/<area>/). Each lives at units/<area>/u<NN>/SPEC.md. Used to verify that the SPEC consumes the dependencies correctly — exact exported names, exact function signatures, exact field names. Read end-to-end; truncated reads on dependencies cause silent signature drift.
5. Existing codebase (required, accessed via Grep, Glob, and Read) — for compatibility checks. The skill greps and reads files to verify SPEC claims about filename conventions, package shapes, framework patterns, existing types, and existing functions in the monorepo.
6. Project guideline files (auto-discovered) — CLAUDE.md, README.md, CONTRIBUTING.md, .editorconfig, and any linter configuration files at the repository root. These are the convention authorities that override default framework conventions when they conflict.
7. Web (accessed via WebSearch and WebFetch) — for library and framework documentation, OSS alternatives, RFCs, package registries (NPM, crates.io, PyPI, etc.), and breaking-change history.
8. Issues and roadmap (required, auto-discovered) — issues/*/ISSUE.md and roadmap/*.md files at the repository root. Used to verify whether items the SPEC defers to "future work" genuinely have a home elsewhere or are phantom deferrals.

Read-set size: 1–3 trigger artifacts + 1 SPEC + 4–7 design artifacts + 1–4 related-unit SPECs + tool reads (codebase, web, issues, roadmap). Within ADD's 10-artifact budget. Read every required input end-to-end before launching subagents — truncated reads produce phantom findings (a QF-NN claiming "INV-12 is uncited" when INV-12 appears on a line that was cut off).

Workflow

The review proceeds in six phases. Phases 1, 3, 4, 5, 6 are sequential. Phase 2 launches four subagents in parallel and waits for all of them to complete before Phase 3 begins.

Phase 1: Context & Citation Index

Read every required input end-to-end. As you read the SPEC, build an in-agent working index of:

• Stable IDs cited: every INV-NN, EP-name, EVT-name, ERR_CODE, SM-{entity}-{state} or SM-{entity}: {from} → {to}, SAGA-name, METRIC-*, SLO-*, SPAN-*, THREAT-NN, MIT-NN, UC-NN, ADR-NN, CFG_NAME, paired with the SPEC section that cites it.
• Dependency imports claimed: every type, function, or symbol the SPEC says it imports from a dependency unit, paired with the dependency unit ID and the SPEC section that imports it.
• File manifest: every file path the SPEC declares (under § 9 File Manifest or equivalent), paired with its declared role.
• Behavioral paths: every ordered behavioral path the SPEC describes — happy path, error paths, edge cases — paired with the SPEC section.
• Deferred items: every phrase in the SPEC that says "deferred to future unit", "out of scope for this unit", "will be addressed in PLAN/IMPLEMENT", or equivalent, paired with the SPEC section and the deferral target if named.
• Decisions visibly deferred to PLAN/IMPLEMENT: every place the SPEC defers a decision that should be made at the SPEC level — wire shape, lock granularity, error code, field name, library choice — even when not explicitly labelled "deferred".