# Validate

Critique an existing design spine without changing it. The synthesis pipeline below is also used at the Reviewer Gate during Create / Update Finalize.

## Orient

Subagent-extract from `.decision-log.md`, sources in frontmatter, `imports/`, `mockups/`, `wireframes/`, `design.md`. Parent assembles from extracts.

## Reviewer Gate

Rubric walker prompt:

> Validate `design.md` as the contract for downstream consumers (architecture, story-dev — human or AI). Can a consumer source-extract cleanly, with every reference resolving and every load-bearing decision committed? Read `{workflow.spine_examples}` first.
>
> **Pass 1 — mechanical coverage.** Per category: extract, then list misses with location citations. No misses = **strong**.
>
> 1. **Flow coverage.** Sources frontmatter → extract every UJ / requirement name. Verify each has a Key Flow with numbered steps, a named climax beat, and a failure path where applicable.
>
> 2. **Token completeness.** Extract every token reference in `design.md`. Verify each defined. **Color tokens missing hex (or light/dark pairs where applicable) are critical** — downstream code mirrors the spine. Platform conventions (native dynamic type, 8pt grid) may stay semantic. Contrast targets stated for load-bearing combinations.
>
> 3. **Component coverage.** Extract every component name used anywhere. Verify each has a Component Patterns row with real rules (anatomy, state cues, sizing — not one-word descriptions).
>
> 4. **State coverage.** Walk every IA surface. List states it should have (empty, cold-load, focus, error, offline, permission-denied — whichever apply). Verify each covered.
>
> 5. **Visual reference coverage.** List every file in `mockups/`, `wireframes/`, `imports/`. Spine links to each inline at the relevant section and names what it illustrates; spine-wins-on-conflict stated once. List orphans and unspecific references.
>
> **Pass 2 — judgment.** Verdict per category (*strong / adequate / thin / broken*); findings only where they add information.
>
> 6. **Bloat & overspecification.** Pixel specs where tokens cover it; source restatement (personas, FRs, scope); prose where a table works; sections no downstream consumer would read; decorative narrative untied to a decision.
>
> 7. **Inheritance discipline.** `sources` frontmatter resolves. UJ / requirement names verbatim from sources. Glossary identical across spine and sources. Component names identical across all sections within the spine.
>
> 8. **Shape fit.** Required default tables present (IA, Voice and Tone, Design Tokens, Component Patterns, State Patterns, Interaction Primitives, Accessibility Floor, Key Flows). Dropped defaults defensible. Required-when-applicable present where triggered (Inspiration when sources / log show reference products or rejects; Responsive when multi-surface or breakpoints). Invented sections earn their place.
>
> Severity = downstream impact, not fix difficulty.
>
> Write to `{doc_workspace}/review-rubric.md`:
>
> ```markdown
> # Design Spine Review — {spine_name}
>
> ## Overall verdict
> [2–3 sentences]
>
> ## 1. Flow coverage — [verdict]
> [What was checked.]
> ### Findings
> - **[critical|high|medium|low]** [finding] (location). *Fix:* [suggestion].
>
> (repeat 2–8)
>
> ## Mechanical notes
> [Name inconsistencies, broken cross-refs, frontmatter completeness, Mermaid syntax.]
> ```
>
> Return ONLY a compact summary: overall verdict, per-section verdicts, finding counts by severity, file path.

The gate may dispatch `{workflow.finalize_reviewers}` and ad-hoc reviewers (accessibility for consumer / regulated). Each writes `review-{slug}.md` and returns a compact summary. Parallel.

## Synthesis pipeline

Under Validate intent, after every reviewer returns, render one consolidated report. Don't skip.

1. Read every `{doc_workspace}/review-*.md`.
2. Fill `{workflow.validation_report_template}`. Grade: *Excellent* = all strong / adequate, no high / critical · *Good* = ≤1 thin, no critical · *Fair* = multiple thin or any high · *Poor* = any broken or critical. Set matching `grade-*` class. Synthesis paragraph lifts the rubric's overall verdict; add a second if extra reviewers shift the picture. One section per rubric category (open if thin / broken), one per extra reviewer (closed, adversarial voice preserved).
3. Write `{doc_workspace}/validation-report.html`.
4. Write the markdown twin `{doc_workspace}/validation-report.md` — same content grouped by severity.
5. Open HTML: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"`. Skip headless.

Re-running overwrites the consolidated report; individual `review-*.md` files persist.

## Markdown twin shape

```markdown
# Validation Report — {spine_name}

- **Spine:** `{spine_path}`
- **Run at:** {ISO timestamp}
- **Grade:** {Excellent | Good | Fair | Poor}

## Overall verdict
{synthesis paragraphs}

## Category verdicts
- Flow coverage — {verdict}
- Token completeness — {verdict}
- Component coverage — {verdict}
- State coverage — {verdict}
- Visual reference coverage — {verdict}
- Bloat & overspecification — {verdict}
- Inheritance discipline — {verdict}
- Shape fit — {verdict}

## Findings by severity

### Critical (n)
**[Category or Reviewer]** — Title (§ location)
{Note}
Fix: {suggested fix}

### High (n) / Medium (n) / Low (n)
...

## Reviewer files
- `review-rubric.md`
- ...
```

## Close

Surface artifact paths. Always offer to roll findings into an Update.