Task: Generate DESIGNREVIEW.md — Design-Suite Gate Review

Task: Generate DESIGN_REVIEW.md — Design-Suite Gate Review

Objective

Produce a DESIGN_REVIEW.md that serves as the mandatory gate at the end of the bootstrap design phases (A–E) of the Agent-Driven Development workflow, and re-runs whenever G8 reconcile applies major top-level edits during continuous implementation. It reviews the eight-artifact design suite — DOMAIN, ARCHITECTURE, INTERFACES, DATA, BEHAVIOR, QUALITY, SECURITY, ERRORS — along three orthogonal axes (cross-artifact consistency, completeness against downstream needs, internal quality of each artifact), catalogues every finding under stable CF-NN / MF-NN / QF-NN IDs with severity, evidence, and a proposed actionable edit, validates every stable-ID citation via a cross-reference matrix, and emits a machine-readable verdict (pass or fix-required) that the orchestrator branches on. An agent reading this document alone can — without opening any of the eight reviewed artifacts — tell which artifacts need regeneration, exactly what content must change, and whether the pipeline may proceed to continuous per-trigger work or must loop back through design.

DESIGN_REVIEW.md is the type-checker of the design phase. It catches the errors that do not manifest within any single artifact but emerge from relationships between them: an invariant declared in DOMAIN but unenforced by a DATA constraint; a wire event declared in INTERFACES but un-emitted by any BEHAVIOR saga; an error code referenced from an endpoint but missing from the ERRORS registry; a use case present in USE_CASES but un-realised by any endpoint or saga. Without this gate these contradictions surface during /spec or /implement, forcing cascade regenerations of downstream artifacts; with it, the fix is localised to the offending design artifact and the pipeline re-enters only the minimum necessary scope. The defining discipline — and the commonest violation — is every finding is actionable, every finding cites evidence, and the verdict field matches the blocking-finding count exactly. Subjective complaints, vague "this is inconsistent" findings, and verdicts that override the blocking-count rule turn the gate into noise.

Inputs

1. DOMAIN.md (required) — ubiquitous vocabulary, bounded contexts, entities, invariants (INV-NN). Reviewed for internal quality; used as the authoritative source for every entity-name and INV-NN citation in other artifacts.
2. ARCHITECTURE.md (required) — components, cross-component flows, architecture decisions (ADR-NN). Used as the authoritative source for every component name referenced elsewhere; reviewed for completeness against DOMAIN contexts.
3. INTERFACES.md (required) — boundaries, endpoints (EP-name), events (EVT-name), authentication, idempotency. Used as the authoritative source for every endpoint and event reference; reviewed for consistency with DOMAIN vocabulary and BEHAVIOR emission timing.
4. DATA.md (required) — storage model, schema, constraints, indexes, sensitive-column inventory. Reviewed for coverage of DOMAIN entities and enforcement of DOMAIN invariants at the schema level.
5. BEHAVIOR.md (required) — state machines (SM-entity-state), sagas (SAGA-name), idempotency keys, event emission timing. Reviewed for coverage of DOMAIN entity lifecycles and consistency with INTERFACES endpoints and events.
6. QUALITY.md (required) — logging, metrics (METRIC-*), SLOs (SLO-*), alerts, performance budgets. Reviewed for coverage of INTERFACES endpoints and BEHAVIOR sagas.
7. SECURITY.md (required) — assets, actors, trust boundaries, threats (THREAT-NN), mitigations (MIT-NN), auth and authorization. Reviewed for coverage of INTERFACES boundaries, USE_CASES actors, and internal threat-to-mitigation closure.
8. ERRORS.md (required) — error code registry (ERR_CODE), HTTP mapping, user-facing messages. Reviewed for coverage of the error codes cited across INTERFACES, BEHAVIOR, QUALITY, and SECURITY.
9. USE_CASES.md (optional — read when use-case-coverage analysis is requested) — the UC-NN registry. Enables § 6 Use-Case Coverage to trace every use case to an endpoint or saga that realises it. Read it when requested; skip the section if not read.
10. PROPOSAL.md (optional — read when cited by QUALITY or SECURITY for numeric targets) — used only to verify that citations in downstream artifacts are faithful (e.g., SLO-push-latency-p95 target cites PROPOSAL verbatim).
11. Surface IAs (optional — read one at a time if requested) — {WEB,CLI,MOBILE,TUI,VOICE}_IA.md. Read at most one per review; reading more than one exhausts the context budget. When not read, § 6 silently skips surface-coverage checks.

Read set size: 8 required artifacts. The eighth is the heaviest step in ADD by design — the review exists because cross-artifact analysis cannot be delegated downward. Optional inputs (9–11) are read only when they add a concrete check; each one consumes context that could otherwise be spent reading the required eight more carefully.

Read all required inputs end-to-end. The single most common failure mode of this skill is truncated reads producing phantom findings — a CF-5 that claims "DOMAIN § 9 has no INV-12" when INV-12 appears on line 1280 of a file that was cut off at line 900. Before writing any finding that asserts absence of an ID, re-scan the referenced artifact's full length.

Workflow

The review proceeds in six phases: context and cross-reference extraction, per-artifact quality pass, pairwise consistency pass, completeness pass, use-case coverage pass (optional), verdict and required-changes synthesis. Phases are sequential — later phases consume the cross-reference index built in Phase 1 — but revisit earlier phases if a later one surfaces a citation that Phase 1 missed.

Before Phase 2, read references/review-checklist.md for the systematic probes applied to each axis. The checklist organises:

• Per-artifact quality probes — eight sections, one per artifact, each listing the internal-quality defects to look for (placeholder language, unresolved open questions, malformed IDs, orphan entries).
• Pairwise consistency probes — ordered pairs (e.g., DOMAIN ↔ DATA, INTERFACES ↔ BEHAVIOR, SECURITY ↔ INTERFACES) with the specific contradictions that arise at each pair.
• Completeness probes — grouped by downstream consumer (per-unit /SPEC.md, /system-verification), each listing the information those steps depend on.
• Cross-reference index recipe — the exact prefixes to extract and match (INV-, EP-, EVT-, ERR_, SM-, SAGA-, METRIC-, SLO-, THREAT-, MIT-, UC-, ADR-, CFG_).