@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/riff-prototypes/SKILL.md

@@ -0,0 +1,637 @@
+---
+tier: lite
+name: riff-prototypes
+description: "DEPRECATED \u2014 use /stage instead. Visual variants with luminary champion-challenger; work absorbed by /stage light size per ADR-020. Retained during 3-month deprecation grace before retirement."
+problem: "DEPRECATED \u2014 use /stage instead. Visual variants with luminary champion-challenger."
+value: "Deprecated skill absorbed into /stage. Points to the new entry point."
+inputs: [Redirects to /stage]
+outputs: [Deprecation notice, Redirect to /stage]
+deprecated: true
+deprecated_in_favor_of: /stage
+deprecated_decision: architecture/decisions/ADR-020-prototype-skill-family-consolidation.md
+user_invocable: true
+disable_model_invocation: false
+composes_baseline: anthropic-frontend-design
+---
+
+> **Baseline composition:** Bassclef's variant authoring composes on top of Anthropic's `frontend-design` skill defaults. Adopters firing plain Claude inherit those defaults; this skill (and `/stage`) extend with luminary champion-challenger commitment + bassclef's design-discipline.
+
+# Prototype Variants — DEPRECATED
+
+> **Deprecation notice (2026-05-12 per ADR-020):** This skill is deprecated in favor of `/stage` (light size). `/stage` already produces variants with luminary champion-challenger. New work should invoke `/stage light` instead. This skill remains invocable during the deprecation grace period (≥3 months) before retirement.
+
+# Prototype Variants — Visual Options Before Construction
+
+Produce 2-3 lightweight static prototypes, each driven by a different
+primary luminary's perspective. The operator views them locally and
+selects a direction before committing to a full build.
+
+## When to use
+
+- At the start of Elaboration (step 0), after Inception passes
+- When the iteration goal's phase is Elaboration or Construction
+- When UI/UX direction is uncertain and the operator wants to see options
+- When `/autonomous start` detects phase=Elaboration and asks about prototypes
+
+Can also be invoked standalone at any time.
+
+## What a prototype IS
+
+- Static HTML + CSS + Tailwind in `docs/prototypes/YYYY-MM-DD-variant-N/`
+- Stubbed data (hardcoded JSON in a `<script>` tag or inline, no API calls)
+- 1-3 pages showing the key interaction (list, detail, form — whatever the scope demands)
+- Viewable via `npx serve docs/prototypes/variant-N/` or `open docs/prototypes/variant-N/index.html`
+- Built in minutes, not hours
+- Screenshotted by the agent using Playwright MCP. When Playwright MCP is not enabled, the skill BLOCKs with `INSTEAD: enable Playwright MCP before continuing`.
+
+## What a prototype IS NOT
+
+- Not a full Next.js app — no routing framework, no app directory
+- Not connected to any database — no Prisma, no API routes
+- Not deployed anywhere — local only
+- Not tested — this is throwaway. Construction builds the real thing.
+- Not production code — it's a visual sketch in HTML
+
+## Procedure
+
+### 1. Read the Inception artifacts
+
+- Product canvas (scope, what survived, what was killed)
+- Risk register (what UX/tech risks exist)
+- Iteration bet (what value/lovability we're proving)
+
+### 2. Choose sprint mode
+
+Use AskUserQuestion to ask:
+
+> **How do you want to run this prototype sprint?**
+>
+> 1. **Bake-off** — I pick the number of variants (2-3). The system
+>    selects luminaries matched to the scope, builds all variants,
+>    runs /visual-review on each, scores them, and recommends a winner
+>    based on the iteration goal's risk + value signals. I approve or
+>    override the recommendation.
+>
+> 2. **Curated** — I pick which luminaries to prototype against, view
+>    the results myself, and choose the winner. Visual review still
+>    runs for evidence, but I make the call.
+
+#### Bake-off mode
+
+The system selects luminaries based on the scope type:
+
+| Scope type | Luminaries selected | Rationale |
+|---|---|---|
+| Data-heavy tools | Norman, Prater, Tufte | Affordance, entity-derived nav, data display |
+| Storytelling/narrative | Lupton, Apple HIG, Cooper | Visual hierarchy, restraint, goal-directed |
+| Dashboard/overview | Tufte, Morville, Material | Data-ink, findability, systematic tokens |
+| Forms/input | Norman, Tidwell, Cooper | Affordance, proven patterns, goals |
+| Emotional/consumer | Walter, Fogg, Lupton | Delight, behavior triggers, storytelling |
+
+If the scope doesn't clearly match one type, ask the operator to pick
+the scope type (not the luminaries — the system handles that).
+
+After visual review scores all variants, the system recommends a winner:
+- Highest usability score is the tiebreaker
+- If scores are close (<2 points apart), recommend the variant that
+  best aligns with the iteration goal's risk signal
+- Present the recommendation with evidence. Operator approves or overrides.
+
+#### Input sources
+
+The luminaries driving each variant come from one of these paths, in priority order:
+
+1. **Operator-private intent grounding (if loaded)** — when an operator-private `/extract-intent` skill is available via `additionalDirectories` (the optional two-repo pattern per `standards/operator-private-discipline.md`), this skill reads its `matched_luminaries` output from the InputArtifact passed in.
+
+2. **Bassclef-core `/pick-luminaries`** — single LLM call against the configured model provider (default Anthropic Haiku). The default bassclef-core path; works for any consumer with an `ANTHROPIC_API_KEY`.
+
+3. **Operator picks** (curated mode) — manual selection from menu.
+
+4. **`/luminary recommend`** — signal scoring (Garrett-plane + primary-domain coverage). Fallback when the picker refuses (no API key, network failure).
+
+5. **Scope-keyword bake-off table** (legacy lines 67-74) — last-resort path for degraded environments.
+
+Ceiling: **5 variants maximum** (4 pure + 1 hybrid, or 5 pure). Beyond
+5, cognitive load and budget outweigh exploration benefit.
+
+**Hybrid variant rule**: A hybrid (two luminaries stacked in one variant)
+is allowed ONLY when the two luminaries operate on **different Garrett
+planes** (strategy / scope / structure / skeleton / surface). Same-plane
+hybrids produce contradictions (which structure wins? which surface
+language?) and must be rejected.
+
+**Hybrid / mashup MUST emit a Carry-Forward Ledger before building.**
+When producing a hybrid from two existing variants (or iterating on
+a selected variant post-sprint), the agent must FIRST read both source
+variant files end-to-end and produce a ledger. No ledger = no build.
+
+```
+## Carry-Forward Ledger
+
+### Source variants read
+- docs/prototypes/YYYY-MM-DD-variant-a-[luminary]/index.html (L1-L400)
+- docs/prototypes/YYYY-MM-DD-variant-b-[luminary]/index.html (L1-L520)
+- docs/prototypes/YYYY-MM-DD-variant-a-[luminary]/README.md
+
+### From Variant A (carrying forward — cite line ranges)
+- [element]: [file:lines] — [why it carries]
+- [element]: [file:lines] — [why it carries]
+
+### From Variant B (carrying forward — cite line ranges)
+- [element]: [file:lines] — [why it carries]
+
+### Changing / replacing (explicit deltas)
+- [element]: was [A's treatment at file:lines] OR [B's] → now [new treatment]
+  — [why the change is needed]
+
+### Dropping (with reason)
+- [element]: was [source:lines] → removed — [reason]
+
+### Inventing (new, not from either source)
+- [element]: — [reason this is new, not a pattern-match to generic UI]
+```
+
+This ledger is the anti-pattern-match gate. Invention is allowed, but
+must be explicit and justified — not the default because the agent
+didn't read the sources.
+
+**Applies equally to**:
+- Hybrid variant in a new sprint (combining two luminary POVs)
+- Post-sprint iteration on a selected variant (carrying it forward
+  with refinements)
+- Extending a variant to new surfaces (e.g., Review Queue variant
+  extended to Outreach) — the new surface must cite what's carrying
+  from the original and what's new
+
+See `.claude/rules/artifact-ingestion.md` — this is the skill-level
+instantiation of that rule for prototype work.
+
+#### Curated mode
+
+Use AskUserQuestion to let the operator pick which luminary perspectives
+to prototype against. Present the full menu organized by discipline:
+
+> **Pick up to 3 luminaries for your prototype variants.**
+> Each variant will be built through that thinker's dominant lens.
+>
+> **UX / Interaction:**
+> - Don Norman — affordance-first, minimal chrome, obvious actions
+> - Jakob Nielsen — 10 usability heuristics, discount usability
+> - Alan Cooper — goal-directed, start from user goals, work backward
+> - Steve Krug — "Don't Make Me Think", intuitive navigation
+> - Sophia Prater — entity-derived, navigation mirrors the domain model
+> - Jenifer Tidwell — proven interaction patterns for common UI problems
+> - Luke Wroblewski — mobile-first, touch-first interaction
+> - Golden Krishna — no-interface thinking, beyond screens
+>
+> **Visual / Typography / Color:**
+> - Ellen Lupton — storytelling hierarchy, the page tells a narrative
+> - Josef Albers — color as context, relative not absolute, test combinations
+> - Eva Heller — color psychology, emotional associations across cultures
+> - Johannes Itten — seven types of color contrast, color harmonics
+> - Edward Tufte — data-ink ratio, maximum information, minimum decoration
+> - Apple HIG — progressive disclosure, clarity, restraint
+> - Google Material — systematic visual language, tokens over ad-hoc
+>
+> **Information Architecture:**
+> - Peter Morville — how content is organized, labeled, navigated
+> - Abby Covert — sense-making, structure from complexity
+> - Richard Saul Wurman — LATCH (Location, Alphabet, Time, Category, Hierarchy)
+> - Jesse James Garrett — multi-layered UX structure (strategy → surface)
+>
+> **Psychology / Persuasion / Emotion:**
+> - BJ Fogg — behavior design, motivation × ability × trigger
+> - Robert Cialdini — persuasion principles (social proof, scarcity, authority)
+> - Aarron Walter — emotional design hierarchy (functional → reliable → usable → pleasurable)
+> - Susan Weinschenk — "The Brain Lady", cognitive science behind user behavior
+
+If the operator doesn't pick, propose 3 based on the scope:
+- **Data-heavy tools** → Norman, Prater, Tufte
+- **Storytelling/narrative** → Lupton, Apple HIG, Cooper
+- **Dashboard/overview** → Tufte, Morville, Material
+- **Forms/input** → Norman, Tidwell, Cooper
+- **Emotional/consumer** → Walter, Fogg, Lupton
+
+In curated mode, the operator also picks the winner after reviewing.
+Visual review evidence is presented but the recommendation is advisory.
+
+#### Winner selection by parent session mode
+
+| Parent mode | Winner selection |
+|-------------|------------------|
+| operator-gated (any flags) | Operator picks after reviewing visual-review output |
+| orchestrator-gated + gate-ux | Operator picks (gate-ux pulls UX back) |
+| orchestrator-gated (no gate-ux) | Orchestrator auto-picks highest composite score |
+
+**Auto-pick logic (orchestrator-gated without gate-ux):**
+
+1. Run `/visual-review` on each variant as normal
+2. Compute composite score per variant:
+   - Visual review score (weighted 60%)
+   - Signal match score from `/luminary recommend` (weighted 30%)
+   - Luminary adherence score (did the variant actually apply the POV?) (weighted 10%)
+3. Orchestrator picks highest composite score as winner
+4. Ties broken by signal match score (stronger match wins)
+5. Write decision to danger-mode summary:
+   ```
+   ## Prototype winner auto-pick
+   - Winner: variant-2 (Norman-dominant)
+   - Composite score: 87/100 (visual 52/60 + signal 27/30 + adherence 8/10)
+   - Runner-up: variant-1 (Prater-dominant) — 81/100
+   - Rationale: [visual review findings summary]
+   - Confidence: medium (two variants within 10 points)
+   ```
+6. Update iteration goal `primary_luminaries` field (LIST form per
+   the collapse-to-single anti-pattern documented in bassclef follow-up
+   promotions) with winner. If the winner variant embodied a pair/triple,
+   write ALL entries — do not collapse. Include role annotations.
+
+**Pair embodiment validation** (extension mode):
+
+When the iteration is extending a prior prototype that carried a
+luminary pair (e.g., "Variant D = Tufte + Morville"), the extension
+prototype MUST embody BOTH luminaries. Validation during visual
+review:
+
+- For each luminary in the carried pair, score adherence 0-10
+  (how strongly did this prototype apply this luminary's POV?)
+- If any luminary's adherence < 5, the extension FAILED pair
+  embodiment. Report specifically which luminary was collapsed.
+- Composite score (for auto-pick) weights pair embodiment: if any
+  luminary adherence < 5, cap composite at 50/100.
+
+Evidence of collapse patterns (see (see bassclef follow-up promotions).:
+- Iteration bet writes "Tufte (carried from Variant D)" — missing Morville
+- Prototype shows dense data but no navigation facets — Tufte applied,
+  Morville ignored
+- Responsibility matrix attribution all cites one luminary — the other
+  wasn't operationalized
+7. All variants (including rejected) remain in `docs/prototypes/` —
+   operator reviews rejected directions alongside winner
+
+**Override**: operator reviewing PR can change `primary_luminary` in
+the iteration goal and re-run `/decompose` if they disagree with the
+auto-pick after seeing results.
+
+#### When X dominates — what the variant actually looks like
+
+Three "data-heavy" variants (Norman, Prater, Tufte) must produce
+genuinely distinct prototypes. If they blur together, the luminary
+signal is being ignored and the sprint has failed its purpose. These
+sketches show what each dominant POV produces. Load the luminary's
+full file (`.claude/luminaries/[slug].md`) before building the variant
+— the signature, core methods, anti-patterns, and worked example drive
+concrete design decisions.
+
+**Prater-dominant** (data-heavy, relational):
+- Primary nav is **object-based**: Deals, Brokers, Sellers, Buyers.
+  Not feature-based ("Search," "Reports").
+- ORCA applied: entity inventory explicit, relationships drive
+  navigation, CTAs per object, attributes layered by priority.
+- **Progressive disclosure** of data: core nouns above the fold;
+  enrichment data behind expansion; audit fields footer-level.
+- Detail views are **componentized** from the object model, not
+  one-off designs.
+- **Signal of success**: users can navigate the domain via object
+  relationships without using search.
+
+**Norman-dominant** (data-heavy, affordance-forward):
+- Every control's affordance is explicit: buttons look clickable,
+  disabled states explain why, hovers confirm interactivity.
+- **Feedback loops** visible for every action: toast, optimistic UI,
+  error recovery with specific cause.
+- **Mapping** explicit: actions visually grouped with their targets
+  (submit near last field, stage-advance near stage indicator).
+- **Constraints** prevent wrong actions structurally (validated
+  fields, disabled transitions missing prerequisites).
+- **Signal of success**: a first-time user can complete primary tasks
+  without documentation.
+
+**Tufte-dominant** (data-heavy, information-density):
+- **Data-ink maximized**: no decorative gridlines, borders, or
+  background cards. Every visual element encodes data.
+- **Small multiples** where one big chart was the obvious choice.
+- **Sparklines** embedded in tables showing trend without dominating
+  layout.
+- **Dense tables** with many rows visible; typography does the
+  hierarchy, not chrome.
+- **Signal of success**: high information-per-pixel ratio, user can
+  see dozens of data points simultaneously without visual noise.
+
+**Rams-dominant** (minimalist, functional):
+- Every element earns its place. Empty space is acceptable, even
+  preferred.
+- No trend-chasing aesthetic flourishes (no neumorphism, no
+  glassmorphism, no gradients-for-gradient's-sake).
+- **Functional honesty**: buttons look like buttons, disabled like
+  disabled, errors like errors.
+- **Subtraction applied**: five features → three features done
+  excellently.
+- **Signal of success**: the product looks as contemporary in 5 years
+  as it does today.
+
+**Ive-dominant** (precision, premium):
+- **Seam resolution**: every state transition designed (hover, focus,
+  active, disabled, loading, error). No default chrome.
+- **Single considered material**: one shadow family, one radius value,
+  one typography family at three weights max.
+- **Invisibility of craft**: users don't notice precision; they feel
+  that it's right.
+- **Removal discipline**: components have minimal prop surface; if you
+  need a fourth variant, the design is wrong.
+- **Signal of success**: the product feels inevitable — as if no other
+  version could exist.
+
+**Lupton-dominant** (content-heavy, typographic):
+- Type carries the hierarchy. Section headings in weight+size, not
+  colored boxes.
+- **Modular scale** enforced (no arbitrary font sizes). **Vertical
+  rhythm** consistent across sections.
+- **Two to three typefaces** max, paired for contrast in family +
+  harmony in proportion.
+- Grid visible in structure but not in decoration.
+- **Signal of success**: content is scannable without reading — eye
+  naturally follows typographic hierarchy.
+
+**Cooper-dominant** (user-goal-forward):
+- Primary persona's goals drive the main surface. Other personas get
+  goal-optimized secondary surfaces, not a feature-subset of the
+  primary.
+- **Top-level nav** matches primary persona's end goals, not feature
+  taxonomy.
+- **Scenarios as acceptance criteria**: each key scenario walks
+  end-to-end; the prototype demonstrates it.
+- **Ruthless focus** on primary persona — secondary-persona needs
+  serve only when they don't compromise the primary.
+- **Signal of success**: primary persona tasks feel natural and fast;
+  secondary tasks are possible but not optimized.
+
+When producing three variants, pick luminaries whose **signal of success
+is genuinely different**. Three data-heavy variants that all claim "clean
+and usable" is a sign the luminaries aren't dominating — the POV should
+be discernible in the sketch without needing the label.
+
+### 3. Build each variant
+
+For each confirmed variant:
+
+1. **Compose the picked luminary's pattern shelves (bassclef#476 LR6).**
+   Read the picked luminary's frontmatter `solves_problems_brownfield:` +
+   `solves_problems_greenfield:` arrays from `.claude/luminaries/<slug>.md`
+   to confirm the imputed problems match the operator's intent.
+   Then compose pattern catalogs from each picked luminary's claimed
+   primary domain:
+   - **UX luminaries** → read `patterns/ux-ai/smarterpatterns/*.md` (LR4 #481) for AI-mediated UX patterns; read `patterns/ux-ix/*.md` if present for interaction patterns
+   - **Visual luminaries** → read `patterns/ux-ai/smarterpatterns/*.md` for AI surface patterns; read Frost atomic-design entries (LR5 #489) for component hierarchy patterns
+   - **Architecture luminaries** (rare in /riff-prototypes) → read `patterns/code/gof/*.md` (LR4 #485) + `patterns/code/fowler-poaa/*.md` (LR5 #490) if a pattern would shape the prototype's structure
+   - When the picked luminary references a pattern not in the catalog, dispatch `/agent-research-spawn` to fill the gap before continuing the variant build (transparent to operator; updates `docs/luminary-problem-pattern-backfill.md` if the luminary is itself unbackfilled)
+   - **Backfill graceful degradation:** Luminaries without `solves_problems_*` frontmatter (57 remaining as of LR6) skip the shelf-composition step; variant build falls back to legacy bake-off scope-keyword table. Operator gets a one-line warning + `/agent-research-spawn` opt-in to backfill on the spot.
+2. Create `docs/prototypes/YYYY-MM-DD-variant-N/index.html`
+3. Include Tailwind via CDN: `<script src="https://cdn.tailwindcss.com"></script>`
+4. Use the project's design tokens if they exist (read `design/design-tokens.css`)
+5. Hardcode 5-10 realistic data records inline (use names/patterns from the domain)
+6. Build the key pages: typically a list view + detail view + primary action
+7. Each variant should feel *distinctly different* — not three shades of the same thing
+8. State at the top of each HTML file which luminary drives it AND which catalog patterns the variant instantiates — cite catalog paths in HTML comments using the same `@pattern <catalog-path>` format defined by `.claude/rules/pattern-annotation.md`. When the variant graduates to production code, the annotations carry forward to the source files where they become hook-validated.
+9. **Mobile viewport is not optional.** Every prototype must specify behavior
+   at ≤768px. At minimum: does the sidebar collapse to a hamburger? Do tables
+   become cards? Do dense grids stack vertically? If you don't design the
+   mobile breakpoint, the Builder will guess — and guess wrong.
+10. **Depth-section: conditional rendering only (bassclef#971 V1).** If
+    the variant HTML includes a "What's underneath" / "If you want depth"
+    section listing the downstream formal artifacts (spec, use case, user
+    stories, IA model, interaction design, GRASP, persona, JTBD), each
+    item MUST follow one of two shapes — never a bare link to an
+    unverified path:
+
+    | Artifact state at variant-write time | Render as |
+    |---|---|
+    | File exists on disk (chain produced it pre-Phase 4) | Real `<a href="…">…</a>` link with `✓ ready` badge |
+    | File does NOT exist yet (chain produces it post-pick) | No link — plain text + `⏳ coming after you pick` badge |
+
+    Check existence using the same write-time check `local-serve.sh`
+    would resolve the link against. Standard layout assumes the gallery
+    is served at the parent of the variant directory, so depth-links
+    use `../<artifact-dir>/<slug>.md` paths.
+
+    At the bottom of the depth-section include one explanatory
+    sentence — exact text adopters see during smoke:
+
+    > The "coming after you pick" items get written for the variant you
+    > select. Pick a variant → that variant's directions get the full
+    > formal write-up.
+
+    Rationale: cold-adopter smoke 2026-06-13 hit 404s on every
+    depth-link because /riff-prototypes was rendering the section
+    BEFORE the chain produced the artifacts. V1 conditional rendering
+    closes the 404 surface without restructuring the chain.
+    V2 (post-chain link rewrite via /prototype-gallery) is bassclef#971
+    follow-up; V3 (pre-Phase 4 chain reorder) is bassclef#968.
+
+Example structure:
+```
+docs/prototypes/2026-04-04-variant-a-norman/
+  index.html          ← list view (affordance-first)
+  detail.html         ← detail view with primary action
+  README.md           ← which luminary, what principle, what to look for
+
+docs/prototypes/2026-04-04-variant-b-lupton/
+  index.html
+  detail.html
+  README.md
+
+docs/prototypes/2026-04-04-variant-c-prater/
+  index.html
+  detail.html
+  README.md
+```
+
+### 3.5. Always emit Anthropic /frontend-design baseline (MUST — champion-challenger)
+
+After building all N luminary-driven variants, ALWAYS dispatch
+Anthropic's `/frontend-design` skill once to produce a baseline variant.
+This is the architectural insurance that lets us measure whether the
+luminary system is adding value over Anthropic's intrinsic frontend
+design skill.
+
+**Why mandatory:** without a measured baseline, the luminary system
+can't prove it's doing real work. If operator picks the baseline
+variant >50% of the time across runs, the luminary approach needs
+review. If the luminary-driven variants beat the baseline consistently,
+the luminary system is paying its rent.
+
+**Procedure**:
+
+1. Output directory: `docs/prototypes/<sprint-slug>/variant-baseline-anthropic/`
+2. Dispatch `/frontend-design` via Skill tool with input prompt that
+   includes ONLY: scope description + value-prop summary + key data
+   shape. **Do NOT pass**:
+   - Luminary guidance ("apply Tufte data-density")
+   - Bassclef's design tokens (`design/tokens/*.css`)
+   - Reference to other variants in the sprint
+   - Iteration bet's `primary_luminaries` field
+
+   The baseline must measure what `/frontend-design` produces *without*
+   bassclef's design system as a constraint. Otherwise the comparison
+   is contaminated.
+
+3. Output: same shape as luminary variants (`index.html` + optional
+   `detail.html` + `README.md`). The README must state:
+   - "**Baseline — Anthropic /frontend-design** (no luminary contamination)"
+   - Date of generation + the prompt used
+   - Explicit note that this variant did NOT inherit bassclef's tokens
+
+4. Gallery flag (consumed by `/prototype-gallery`): the variant
+   directory name `variant-baseline-anthropic` is the marker.
+   `/prototype-gallery` SHOULD render baseline cards distinctively
+   (different border, "Baseline" badge, or annotation in card body)
+   so operators can tell at-a-glance which is the champion vs.
+   challenger.
+
+5. Comparison signal: when operator selects a winner (or auto-pick
+   fires), record `selected_variant: <slug>` AND `is_baseline: <bool>`
+   in `preview-state.yml` so the champion/challenger ratio can be
+   audited over time.
+
+**What stays luminary-driven, what goes baseline**:
+
+| Concern | Luminary variants (N) | Baseline (1) |
+|---|---|---|
+| Driver | Specific luminary's POV (Tufte, Norman, etc.) | Anthropic's frontend-design skill |
+| Design tokens | `design/tokens/<product>.css` if exists | None (clean comparison) |
+| Iteration bet primary_luminaries | Reads + applies | Ignores |
+| Sprint-scope context | Full | Same scope; no luminary context |
+| Output dir | `variant-<letter>-<luminary>/` | `variant-baseline-anthropic/` |
+| Gallery treatment | Standard card | Baseline-flagged card |
+
+**Operator override**: a future flag `--no-baseline` may suppress this
+behavior for runs where the operator explicitly doesn't want the
+comparison (e.g., already-validated direction, just doing variants of
+the chosen luminary). Default is always-on per step-11b's contract.
+
+### 4. Visual review each variant (MUST gate)
+
+After building each variant, run `/visual-review` on it. This is not
+optional — structured evaluation replaces subjective preference.
+
+For each variant:
+1. Serve it: `npx serve docs/prototypes/variant-N/ -l 3333`
+2. Run `/visual-review` — this screenshots, evaluates against the usability
+   standard, and scores through the variant's dominant luminary AND its
+   complement evaluators (see visual-review skill's complement pairs table)
+3. The report goes to `docs/visual-reviews/YYYY-MM-DD-prototype-variant-N.md`
+4. Kill the server after evaluation
+
+After all variants are evaluated, produce the **prototype comparison table**
+(see visual-review skill's "Prototype Variant Evaluation" section):
+- Usability scores per variant
+- Strongest/weakest principles per variant
+- Evidence-based recommendation aligned to iteration goal risk + value
+
+If Playwright MCP is not available, perform manual evaluation and note
+"manual — no screenshot" in each report.
+
+### 5. Commit the prototypes + reviews
+
+```bash
+git add docs/prototypes/ docs/visual-reviews/
+git commit -m "docs: prototype sprint — N variants for [scope] with visual reviews"
+```
+
+### 6. Present results (mode-dependent)
+
+**Bake-off mode:**
+
+> **Prototype Bake-off complete.**
+>
+> **Visual review comparison:**
+> [insert comparison table from Step 4]
+>
+> **Winner: Variant [X] ([luminary])** — [evidence: highest usability
+> score + best alignment with iteration goal's risk/value signals]
+>
+> Elements worth carrying from other variants: [specific things]
+>
+> **Approve this winner, or override?**
+> 1. Approve — proceed with [luminary] as primary
+> 2. Override — I want [different variant]
+> 3. Reject all — need different directions
+
+In bake-off mode, the system auto-selects based on scores. The operator
+confirms or overrides. If scores are within 2 points, present it as a
+close call and explain the tiebreaker rationale.
+
+**Curated mode:**
+
+> **Prototype Sprint complete. View locally:**
+>
+> ```bash
+> npx serve docs/prototypes/2026-04-04-variant-a-norman/ -l 3001
+> npx serve docs/prototypes/2026-04-04-variant-b-lupton/ -l 3002
+> npx serve docs/prototypes/2026-04-04-variant-c-prater/ -l 3003
+> ```
+>
+> **Visual review comparison:**
+> [insert comparison table from Step 4]
+>
+> **Recommendation** (advisory): [variant] — [evidence-based rationale]
+>
+> Each variant has a README + visual review report. Which direction?
+> You can pick one, combine elements, or reject all.
+
+In curated mode, the operator makes the final call. The visual review
+comparison is evidence, not a decision.
+
+### 7. Selection → pipeline to Construction
+
+Whether auto-selected (bake-off) or operator-chosen (curated), the
+winner triggers a defined pipeline:
+
+1. **Set primary luminary**: Selected variant's luminary becomes
+   `primary_luminary:` in the iteration goal
+2. **Set complement evaluators**: Look up the complement pair in the
+   visual-review skill — these luminaries will evaluate ALL subsequent
+   UI work in this iteration
+3. **Run /ux-migration** (MUST gate — cannot skip):
+   - Component-level visual diff (every element, current vs. target)
+   - Design token extraction (concrete values from prototype HTML)
+   - Prototype HTML → React component mapping table
+   - Work packages with size/risk and dependency-aware build order
+   - Foundation work package first (shadcn init, tokens, shared layout)
+   - Output: migration spec at `docs/specs/ux-migration-*.md`
+   - This spec becomes the Builder's checklist for Construction
+4. **Designer runs Elaboration**: JTBD → HTA → IA → interaction design,
+   all guided by the selected luminary's principles
+5. **Foundation checkpoint**: shadcn init + design tokens + shared layout
+   committed and verified BEFORE any page work starts
+6. **Construction**: Builder implements work packages against the
+   migration spec checklist (not memory, not intuition)
+7. **Every UI commit**: triggers `/visual-review` with complement evaluators
+8. **Visual pass complete gate**: after ALL work packages, screenshot
+   every page side-by-side against prototype. Pass/fail matrix.
+
+The prototype defines the visual direction for Construction. IA structure
+and visual treatment are ONE thing, not two separate passes. When the
+Builder constructs pages that the prototype covered, they must look like
+the prototype — same layout, same typography, same component patterns.
+Separating "structure now, visuals later" produces pages nobody can
+validate because they don't look like what was designed.
+
+The prototype is not a pixel-perfect spec — exact spacing and colors
+may evolve. But the fundamental choices (tables vs. cards, sidebar vs.
+top nav, dense vs. spacious) carry through to Construction unchanged.
+
+## Rules
+
+- Prototypes are throwaway — never reference them as the implementation spec
+- Each variant must be *distinctly different* in approach, not just color swaps
+- Hardcoded data must be realistic (domain-appropriate names, values, patterns)
+- Keep it simple: vanilla HTML + Tailwind CDN. No frameworks. No build steps.
+- If the operator rejects all variants, that's data — ask what's missing and iterate
+- Maximum 3 luminary-driven variants per sprint (PLUS the always-on Anthropic baseline = 4 total max). More than 3 luminary variants creates decision fatigue.
+- **Anthropic /frontend-design baseline is always emitted** (per step-11b champion-challenger). Skip only via explicit `--no-baseline` operator override (rare). Baseline must NOT inherit bassclef's design tokens or luminary context — clean comparison or no comparison.
+- **Capture champion-challenger signal**: when operator selects a winner, write `selected_variant` + `is_baseline` to `preview-state.yml`. Champion-challenger ratio audits across runs.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.