BMAD-METHOD/src/bmm-skills/2-plan-workflows/bmad-ux/references/validate.md

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:

# 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

# 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.