@ritualai/cli 0.7.12 → 0.7.14

package/skills/kiro/ritual/references/build-flow.md

@@ -197,7 +197,7 @@ Steps:
    >   - {state-specific call-to-action — see table below}
    >
    > Recommended: resume one if it matches this work.
-   > Reply with a number/name to resume, `suggest` to find high-leverage candidates from repo + workspace history, or `proceed` to start fresh.
+   > Reply with a number/name to resume, `suggest` to find high-leverage candidates from repo + workspace history, `delete N` to remove a duplicate/misfire, or `proceed` to start fresh.
 
    If `raw_input = null`, frame this as the user's no-arg start screen:
 
@@ -211,6 +211,7 @@ Steps:
    > Reply with:
    > - a number/name to resume
    > - `suggest` to have me look for high-leverage candidates from repo + workspace history
+   > - `delete N` to remove a duplicate/misfire from this list (soft-delete; recoverable)
    > - a feature/problem description to start fresh
    > - `none` to exit
 
@@ -285,6 +286,30 @@ Steps:
 
 6. **If the user picks "start fresh":** continue to Step 2 normally. The new exploration will sit alongside the existing ones; they're independent rows in the workspace.
 
+6a. **If the user picks `delete N` / "remove this from the list":**
+
+   This path handles duplicates and misfires that pollute the resume picker. Common shape: user accidentally created a near-duplicate exploration (started fresh thinking the original was unrecoverable), or a NOT_STARTED row from a typo / wrong-scope misfire that never converged. Eiman hit this in `nebula` on 2026-05-14 — two `Nerve-center /home dashboard` rows, no way to clear the unwanted one. This option fixes that.
+
+   Steps:
+
+   a. **Resolve `N` to an exploration_id.** The user replied `delete 2` referencing the numbered list rendered in step 3. Pick the exploration at that index. If they typed a name instead (`delete "Nerve-center duplicate"`), match by `name` (case-insensitive, exact or prefix).
+
+   b. **Show the target + ask for explicit confirmation** *(CLI Tenet #2 — single decisive proposal, not a 4-option menu)*:
+
+      > About to archive: **{name}** ({recommendationCount} rec{s}, {openDeferralsCount} open deferral{s}, last updated {relative time}).
+      >
+      > This soft-deletes the row — the full record (matters, questions, recs, attestations, decisions) is preserved for audit. The exploration disappears from this and future resume pickers. Restore is admin-only and not exposed in the CLI today.
+      >
+      > **(y/N)** — y to archive, anything else to cancel.
+
+   c. **[USER PAUSE]** — wait for `y` / `yes` (case-insensitive). Anything else = cancel back to the picker without calling the tool. Don't lecture; just say "Cancelled. Here's the picker again:" and re-render the menu.
+
+   d. **Call `mcp__ritual__archive_exploration(exploration_id)`.** On error (404 / 403 / 5xx), surface the failure and re-render the menu — don't silently swallow.
+
+   e. **Re-render the menu.** After successful archive, refresh the list (call `mcp__ritual__list_explorations` again) and show the updated picker. Lead with: "Archived **{name}**. Updated workspace:" — don't make the user re-derive what happened. Then return to step 4 ([USER PAUSE]) — the user can pick resume / suggest / fresh / `delete M` again.
+
+   f. **Anti-pattern**: do NOT auto-pick "start fresh" or "resume the survivor" after a delete. The user chose to clean up, not to commit to a next step.
+
 6b. **If the user picks `suggest` / "help me find the highest-leverage thing":**
 
    This path is for the "I have context but no concrete problem yet" case. The agent does a light workspace scan FIRST so suggestions land on real codebase and prior-deferral signals, not generic advice. This is **not** focused feature recon because no problem has been selected yet; focused recon still happens after the user picks a candidate.
@@ -1391,7 +1416,54 @@ Reply `1` or `2`. Reply `pause` to stop here.
 
 If they pick 1, call `start_agentic_run` with `stop_after: 'answers'` and continue to Step 8.5 when it pauses. If they pick 2, call without `stop_after` and continue to Step 9 when complete.
 
-Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 5` (always 5 — never escalate to 15/20/25)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays 5; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits. Print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
+##### 8.0 — "You're unblocked" pre-roll (right after `start_agentic_run` returns the run_id)
+
+**Lock the product promise BEFORE you enter the polling loop.** The run continues server-side; the user is free to step away. The polling loop becomes the agent's job, not the user's obligation.
+
+Tier the pre-roll by projected duration. Latency baseline: ~15s/question (V5.2 + KG injection, calibrate quarterly against `recs-pipeline.ts` eval results). Multiply the picked-question count by 15s, divide by 60 to get minutes.
+
+**Projected ≤ 2 min** — skip the pre-roll entirely. The polling micro-copy below covers the framing.
+
+**Projected 2–20 min** — warm framing:
+
+```text
+Deep reasoning run started — this may take ~{minutes} minutes.
+
+You're unblocked: the run continues server-side while you do other work.
+Grab coffee, switch tasks, or close the terminal safely.
+
+Live progress:
+  ritual status --watch
+
+Come back later:
+  /ritual resume
+```
+
+**Projected 20+ min** — longer framing:
+
+```text
+Long reasoning run started — this one may take 20+ minutes.
+
+You can safely step away; the run continues server-side even if this terminal
+closes. For live progress:
+
+  ritual status --watch
+
+To come back later:
+  /ritual resume
+```
+
+The two affordances (`ritual status --watch` from a second terminal, `/ritual resume` later) are NOT modes the user has to opt into — they're the natural escape hatches the user can reach for without re-engaging this session. Do not introduce a `reply watch` mode in this SKILL; the CLI command IS the watch affordance.
+
+##### 8.1 — Polling loop
+
+Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 5` (always 5 — never escalate to 15/20/25)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays 5; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
+
+**On the FIRST poll only** (not every poll), prepend one line that locks the "background execution is default" mental model:
+
+> I'll keep working in the background. Use `ritual status --watch` if you want to follow along live.
+
+Then print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
 
 > Agentic run: {progress_pct}% — {current_step}
 
@@ -1488,7 +1560,11 @@ For each question's loop:
 
 #### Step 9 — Review and accept recommendations (grouped, role-aware)
 
-Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of recommendations. Each rec includes:
+**Use `mcp__ritual__get_recommendations_preview(exploration_id)` for the Step 9.1 landing screen.** It returns a server-rendered preview with `previewText` (terminal-formatted, hard-wrapped at 78 cols — print verbatim), `idMap` (`R1..RN` → uuid lookup for resolving `accept R3` / `detail R7`), `actions` (role-aware structured command list), `categoryGroups` (structured grouped list for non-terminal surfaces), `actionHint`, `scopeLine`, and `totalCount`. The server already handles role detection (admin vs collaborator) and filters out `approved`/`rejected` recs.
+
+Use `mcp__ritual__get_recommendations(exploration_id)` (the raw array) only when you need fields not in the preview — full `metadata.acceptance_criteria[]`, `metadata.explainability` rationale chain, `metadata.labels[]`, etc. The detail card in 9.3 (`detail R{N}`) loads from the raw tool keyed by the uuid you got from `idMap`.
+
+Each raw rec includes:
 
 - top-level: `id`, `title`, `content` (summary), `status`, `priority`, `points`, `confidence`
 - `metadata.category.name` — **the load-bearing grouping key** (one rec → one category)
@@ -1496,21 +1572,62 @@ Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of
 - `metadata.explainability` — `rationale` (chained `→` arrow string), `faq_references[]`, `problem_alignment`, `inferred_elements`, optional `initial_input_analysis`
 - `metadata.labels[]` — secondary tags
 
-**Role model — load-bearing**: only **admins** can accept recommendations (call `accept_recommendations`). **Collaborators** can read, comment, and proceed to implement, but they cannot move recs from `draft`/`pending_review` to `approved`. Respect this so a collaborator running `/ritual build` doesn't hit a 403 mid-flow and lose context.
+**Role model — load-bearing**: only **admins** can accept recommendations (call `accept_recommendations`). **Collaborators** can read, comment, and proceed to implement, but they cannot move recs from `draft`/`pending_review` to `approved`. The preview API handles this automatically — the `actions` list and `actionHint` are gated on the caller's workspace role; admins see `accept recommended` while everyone else sees `request admin review` plus the optional `continue` (implement-ahead) path. Respect what the preview returns; don't substitute it.
 
 If you don't already know the user's role on this workspace, prefer the workspace member endpoint or cached role from `/ritual init`. When unavailable, ask plainly: *"Are you the workspace admin or a collaborator?"* Do not attempt acceptance blindly unless the user explicitly says to accept.
 
 **Vocabulary**: do NOT use "Reasoning chain" or "reasoning_chain" in user-facing copy. The user-visible label is **"Why this"** — a 4-line Problem / Discovery / Tradeoff / Recommendation breakdown derived from the rationale field. "Reasoning chain" sounds like internal model chain-of-thought; "Why this" is product-native.
 
-##### 9.1 — Landing screen: grouped category summary + compact scope
+##### 9.1 — Landing screen: server-rendered preview (primary path)
 
 The recommendations review is the most-read screen in the whole build flow.
 
+**Primary path — print the server preview verbatim:**
+
+```text
+1. Call mcp__ritual__get_recommendations_preview(exploration_id).
+
+2. Response shape:
+     {
+       terminalPreviewText: "...",   // present for surface=terminal (default)
+       uiPreview: {                   // always present
+         stage: "recommendations",
+         stageIndex: 4, stageCount: 6,
+         scopeLine, stats, categoryGroups,
+         idMap, actions
+       }
+     }
+
+3. Print response.terminalPreviewText VERBATIM. Do not re-render,
+   re-wrap, re-number, or add a leading "Here are your recommendations..."
+   line. The server already laid out the build rail, scope, grouped recs,
+   and role-aware action hint at 78-col wrap.
+
+4. Remember response.uiPreview.idMap so you can resolve user input — when
+   they reply `accept R3` or `detail R7`, look up `R{N}` → uuid in
+   idMap and use that uuid in the follow-up MCP call (accept_recommendations,
+   get_recommendations).
+
+5. response.uiPreview.actions is for mobile/web button rendering — terminal
+   flow ignores it (action hint copy is already inside terminalPreviewText).
+   Each action carries `style: "primary" | "secondary"` so a non-terminal
+   UI knows which is the call-to-action.
+```
+
+The server controls the rendering shape (category numbering, R-IDs, titles-only, 78-col wrap, role-aware action hint). Your job is to print and look up — not to invent labels, re-group, or add commentary.
+
+**Fallback path — if the preview tool is unavailable or returns a non-200**: render per the contract block below. The contract is the same shape the server uses, so a mismatch between server-rendered and agent-rendered output is unlikely. The fallback exists for older MCP servers that haven't deployed the preview endpoint yet.
+
 ```text
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-STEP 9.1 RENDERING CONTRACT — non-negotiable
+STEP 9.1 RENDERING CONTRACT (FALLBACK) — non-negotiable
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Use this contract ONLY if get_recommendations_preview is unavailable
+(older MCP server) or returns an error. Otherwise, print the preview
+verbatim per the Primary path above.
+
+
 Landing view is for SELECTION, not reading. Full prose belongs in 9.3.
 
 ✓ DO:
@@ -1913,18 +2030,97 @@ Build brief ready
   · `refine` — something's off; tell me what and I'll regenerate
   · `drill {N}` — drill into RB-{N} before deciding
 
-Reply `pause` to stop here.
+Before `go`, you can run `ux-review` for a design-quality pass on the brief (recommended for UI/UX features — produces `UX-REVIEW.md` and a tailored plan-mode prompt so plan mode stops asking you the same UX questions it always does). Reply `pause` to stop here.
 ```
 
 Branch by user response. Accept `go`, `y`, `yes`, `proceed`, `continue`, `next` as the visible-CTA path (do not display all aliases):
 
 - **`go` / proceed / yes / y**: continue to Step 11.
+- **`ux-review` / review / `ux`**: continue to Step 10.5 (writes `UX-REVIEW.md`, then continues to Step 11 with the tailored plan-mode prompt). Opt-in; absence is the existing path.
 - **`refine`**: ask what's off, then call `generate_build_brief` with `force: true` after applying their feedback to the exploration (typically a recommendation re-accept or a requirement adjustment via the web UI).
 - **`drill {N}`**: open RB-{N} in the markdown, discuss inline, then loop back to the gate above.
 - **`pause`**: stop here. The brief is on disk; the user can resume with `/ritual resume`.
 
 **Pulse (Step 10 done):** Emit a pulse — this often crosses into **Implementation-ready** (90%+). Render full when that crossing happens. Use the build-brief celebration line: `✓ Build brief ready — discovery has become an implementation path.` If still below 90% (e.g. brief flagged residual debt), surface that in the pulse line itself and propose addressing it before coding.
 
+#### Step 10.5 — Optional UX brief review (entered ONLY when the user picks `ux-review` at Step 10d)
+
+This step is opt-in. If the user picked `go` at Step 10d, skip directly to Step 11. The `ux-review` path is reached only when the user explicitly asks for it at the Step 10d gate — there is no auto-gating in this MVP (later iterations may use Stage E's UI-surface classifier to suggest the path automatically; see `backlog_design_recon_stage_e.md`).
+
+Purpose: make the coding agent reason about the experience BEFORE it reasons about files. Plan mode otherwise interrogates the user for the same 10-question UX checklist on every UI-shaped feature. Paying for it once at the right moment — with the brief and the codebase both available — is cheaper than paying it implicitly through plan-mode interrogation.
+
+This step is **SKILL-only — no MCP tool, no LLM-cost on Ritual's API.** The analysis happens locally in the calling agent because the agent is the one with repo access. The reference `references/ui-ux-checklist.md` is the canonical instruction set (methodology + output schema + plan-mode prompt template); this Step 10.5 is the thin orchestration layer that drives the agent through it.
+
+Steps:
+
+1. **Tell the user what's about to happen** (one line, not a multi-line pre-roll):
+
+   > Running a design-quality pass on the brief. Reading `BUILD-BRIEF.md`, mining the repo for existing UI patterns, writing `UX-REVIEW.md` — about 30–60 seconds.
+
+2. **Read `references/ui-ux-checklist.md`** for the methodology, output schema, and plan-mode prompt template. **Walk the methodology in order — do not skip to the output schema.** The methodology's six steps (read brief → identify UI surfaces → find repo analogues → compare brief vs analogues → fill schema with evidence → generate tailored plan-mode prompt) are load-bearing; the output schema only gets filled correctly when the analysis upstream is done.
+
+3. **Read `BUILD-BRIEF.md`** end-to-end. Classify what it covers vs what it's silent on. The brief itself is the input signal — the review's value is on the gaps and codebase-grounding, not on re-deriving brief content.
+
+4. **Mine the repo for existing UI analogues.** Use Grep / Glob / Read against the implied UI surfaces from the brief. Cite file paths in the review; every claim must trace back to either a brief line or a real repo file. **Do not fabricate analogues** — if `Grep` returns nothing, the surface is "new work," not a hallucinated path.
+
+5. **Write `UX-REVIEW.md`** to disk alongside `BUILD-BRIEF.md` (same directory — repo root or `.ritual/`, whichever the brief landed in). Use the exact output schema from the reference file. Prepend the Ritual attribution header:
+
+   ```markdown
+   <!--
+   Generated by Ritual — UX brief review
+   Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+   Source brief: BUILD-BRIEF.md
+   Do not remove this header; it preserves implementation lineage.
+   -->
+   ```
+
+   If a `UX-REVIEW.md` already exists:
+   - **Same exploration**: silent overwrite + one-line note in the summary.
+   - **Different exploration**: confirm before overwriting (same convention as `BUILD-BRIEF.md` in Step 10c — *"A `UX-REVIEW.md` already exists from `{previous}`. Overwrite, or save-to-`UX-REVIEW-{slug}.md`?"*).
+
+6. **Print a compact CLI summary** — the file path + the load-bearing findings only, capped at ≤ 10 lines (CLI Tenet #1, #6):
+
+   ```
+   ✓ UX review ready — `UX-REVIEW.md` is on disk.
+
+   Mismatches surfaced: {N}
+     {first mismatch one-liner — brief X vs analogue Y}
+     {second mismatch one-liner}
+
+   Gaps surfaced: {M}
+     {first gap one-liner — brief silent on Z, codebase default is W}
+
+   New-work surfaces: {K}
+     {first new-work surface one-liner}
+
+   Plan mode will read this first when you proceed to `go`.
+   ```
+
+   Rules:
+   - Cap each list at 3 entries. The full set is in the file.
+   - Omit any list that's empty (e.g. "Mismatches surfaced: 0" → don't print the line).
+   - If ALL THREE lists are empty: the brief is unusually complete. Print one line: *"Brief is unusually complete — no mismatches, gaps, or new-work surfaces. Plan mode will verify state coverage against codebase."*
+
+7. **Offer to open the file** — same OS-aware affordance as Step 10c (VS Code → idea → $EDITOR → macOS open). Single yes/no, never a multi-way picker.
+
+8. **Return to the Step 10d gate** with the updated framing — `UX-REVIEW.md` is now part of the implementation context:
+
+   ```text
+   Reply `go` to start implementation with the UX review as plan-mode input,
+   or `refine` / `drill {N}` / `pause` per the earlier options.
+   ```
+
+   When the user replies `go`, continue to Step 11 with the explicit instruction (passed to plan mode) to read both `BUILD-BRIEF.md` AND `UX-REVIEW.md`, and to use the "Plan Mode Prompt" block at the bottom of `UX-REVIEW.md` as its first numbered list — not a generic plan.
+
+**Anti-patterns to avoid in this step:**
+
+- **Don't render the full `UX-REVIEW.md` to the terminal.** It belongs in the file; the CLI surface is the summary plus the path.
+- **Don't auto-`go` after writing the file.** The user explicitly opted into the review — let them open the file and decide when to proceed.
+- **Don't enter plan mode mid-step.** Plan mode is Step 11. This step writes the artifact plan mode will read.
+- **Don't propose visual designs.** This is a planning packet, not a design tool. Where the codebase has no design system, surface that fact and route back to the user.
+
+**Pulse (Step 10.5 done):** Re-emit the Step 10 pulse if the review surfaced material gaps or mismatches — Readiness can dip back below 90% when significant UX work is flagged that the brief didn't capture. If the review came back clean (zero mismatches, zero gaps, zero new-work), keep the existing pulse — the brief was already implementation-ready.
+
 #### Step 11 — Implement
 
 This step happens **inside** the same `/ritual build` chat if the agent is also the coding agent (Claude Code / Cursor / etc.), or hand-off if the user is implementing themselves.
@@ -1975,7 +2171,7 @@ Next: I'll create a feature branch, then start on RB-1.
 
 ##### 11.1 — Implement
 
-1. Take the build brief as input.
+1. Take the build brief as input. **If `UX-REVIEW.md` also exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), read it too.** When both files are present, use the "Plan Mode Prompt" block at the bottom of `UX-REVIEW.md` as the FIRST input to plan mode — its numbered list of mismatches / gaps / new-work surfaces is the tailored agenda. The generic plan-mode template is the fallback for when only the brief exists.
 2. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to make the code change.
 3. Run tests, lint, build per the repo's conventions.
 4. Track each architectural decision as you go — the input to Step 12's `sync_implementation` call. Per decision, write down: `area`, `choice`, `alternatives_considered`, `rationale`, `source_recommendation_id` (the RB-N or recommendation id the decision implements). This is what makes lineage queryable later — don't skip it.
@@ -2228,6 +2424,7 @@ This subcommand exclusively uses vNext MCP tools, in the order they appear:
 3. `mcp__ritual__list_explorations` (Step 1.5 — resume vs start, with state badges)
 4. `mcp__ritual__suggest_high_leverage_problems` (Step 1.5 step 6b — option 3, "help me find the highest-leverage thing")
 5. `mcp__ritual__check_exploration_overlap` (Step 1.5 step 8 — pre-creation overlap detection before "start fresh")
+5a. `mcp__ritual__archive_exploration` (Step 1.5 step 6a — soft-delete a duplicate/misfire when user picks `delete N` from the resume menu)
 6. `mcp__ritual__list_templates` (Step 2)
 7. `mcp__ritual__generate_considerations` (Step 4)
 8. `mcp__ritual__refine_considerations` (Step 4.2, iteration only)
@@ -2255,7 +2452,7 @@ This subcommand exclusively uses vNext MCP tools, in the order they appear:
 24c. `mcp__ritual__list_knowledge_sources` (used inline by Step 3.5 to show already-attached refs on resume; also called by `/ritual context-pulse` CP2 for Reference Grounding count)
 25. `mcp__ritual__sync_implementation` (Step 12)
 
-31 of the 40 vNext tools. The other 9 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`) are situational, not part of the linear build flow.
+32 of the 43 vNext tools. The other 11 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`) are situational, not part of the linear build flow.
 
 ### After this subcommand
 

package/skills/kiro/ritual/references/ui-ux-checklist.md

@@ -0,0 +1,198 @@
+## UX brief review — methodology + output schema
+
+Reference for `/ritual build` Step 10.5 (the opt-in `ux-review` path) and any standalone caller that needs the same shape.
+
+The brief that came out of Step 10 is implementation-ready from a *what* standpoint (RBs, requirements, acceptance criteria). This review is implementation-ready from an *experience* standpoint — the things coding-agent plan mode otherwise interrogates the user for, surfaced and answered with evidence before any code is touched.
+
+The output is a single file, `UX-REVIEW.md`, written alongside `BUILD-BRIEF.md`. It is repo-grounded (every claim cites a brief line or a repo analogue), brief-aware (does not re-derive what the brief already nails), and auditable (gaps and mismatches surface explicitly rather than buried in prose).
+
+---
+
+### Core principle
+
+**Make the coding agent reason about the experience before it reasons about files.**
+
+The plan mode prompt at the end of `UX-REVIEW.md` is the load-bearing artifact. Plan mode reads it on entry instead of inventing its own questions.
+
+---
+
+### Methodology (chain of thought — execute in this order)
+
+Do NOT skip to the output schema. Walk these six steps; the schema only gets filled correctly when the analysis upstream is done.
+
+**1. Read the brief end-to-end first.**
+
+Open `BUILD-BRIEF.md`. Identify what it covers vs what it's silent on. The brief itself is signal:
+
+- An exhaustive states table → most state sections will be "covered in BUILD-BRIEF.md §X; no additions needed."
+- A missing copy section → that's where to focus; copy is high-leverage and almost always under-specified.
+- A "Non-goals" section listing UI surfaces explicitly out of scope → DO NOT add UX recommendations that contradict the non-goals.
+
+Output of this step: a one-line classification of the brief — what's well-covered (skip in the review), what's thin (deep-dive in the review), what's silent (gap-flag in the review).
+
+**2. Identify the UI surfaces the brief implies.**
+
+Pull a list of every screen, component, modal, drawer, form, list, page, route, view, dashboard, panel, toast, banner, etc. that the brief mentions or implies. Be literal — if the brief says "users see a confirmation," that implies at minimum: a confirmation surface + the action that triggered it + the dismissal path.
+
+Output of this step: a flat list of UI surfaces with one-line "purpose" each.
+
+**3. For each implied surface, find existing analogues in the repo.**
+
+Use Grep / Glob / Read. Search by:
+
+- Exact name: `<surface>` (e.g. `ConfirmModal`, `EmptyState`, `DrawerPanel`).
+- Component-library import: imports from the repo's design-system package, `@radix-ui/*`, `shadcn-ui`, `@mui/material`, `@chakra-ui/*`, etc.
+- Route shape: similar `/path/to/feature` routes already in the app.
+- Sibling features: features one directory over that ship the same shape.
+
+Output of this step: for each implied surface from step 2, the closest existing analogue (file path + ~5-10 line excerpt of the relevant pattern) OR `"no analogue found — new pattern needed"`.
+
+**4. Compare brief requirements vs analogue patterns.**
+
+For each (implied surface, analogue) pair, classify:
+
+- **Covered** — brief specifies X, analogue already handles X. Skip in the review or note as "use existing pattern, no decisions needed."
+- **Mismatch** — brief asks for X, analogue does Y. Surface for plan mode: is this intentional (the new feature deliberately diverges) or unintentional (the brief was written without knowing the analogue exists)?
+- **Gap** — brief silent on X, but X is standard in this codebase (the analogue always handles X). Surface for plan mode: the brief should specify, or the agent should follow the codebase default.
+- **New work** — brief specifies X, no analogue. Flag: this surface needs to be designed, not extended.
+
+Output of this step: three lists — mismatches, gaps, new-work surfaces. With evidence (file path / line / brief reference) on each entry.
+
+**5. Fill the 12 sections WITH EVIDENCE.**
+
+Now — and only now — fill the output schema below. Rules:
+
+- Each claim cites either a `BUILD-BRIEF.md §X` line OR a repo file path. Both is better.
+- Sections the brief already covers get one line: *"Covered in BUILD-BRIEF.md §<section>; no additions needed."* Do not re-derive.
+- Sections the brief is silent on but the codebase implies a default for: *"Brief silent. Codebase default (`<path>`): <one-line pattern>. Recommend following the default."*
+- Sections that are real gaps: *"Brief silent. No codebase default. Plan mode must address: <one-line question>."*
+- States that the brief does not require: omit. An empty state entry means "the brief does not require this state and the analogue does not either" — that is a valid signal.
+
+**6. Generate the plan-mode prompt with the surfaced findings.**
+
+The plan-mode prompt is NOT generic. Its first three numbered items are the surfaced mismatches, gaps, and new-work surfaces from step 4. Plan mode then has to address those specifically — not walk a generic 10-step plan.
+
+The plan-mode prompt MUST end with the literal sentence:
+
+> Do not start coding until the plan is approved.
+
+---
+
+### Output schema — `UX-REVIEW.md`
+
+Render exactly the sections below. Every section MUST exist (use the "Covered in BUILD-BRIEF.md" / "Brief silent" patterns rather than skipping). Sub-state entries under "States" are the only optional content.
+
+```markdown
+<!--
+Generated by Ritual — UX brief review
+Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+Source brief: BUILD-BRIEF.md
+Do not remove this header; it preserves implementation lineage.
+-->
+
+# UX Brief Review — {exploration name}
+
+## User Goal
+
+{What the user is trying to accomplish. Cite the brief's Goal section. One paragraph max.}
+
+## Primary Flow
+
+{Step-by-step happy path from the user's perspective. Cite brief lines. If the brief already enumerates this, write "Covered in BUILD-BRIEF.md §<section>" + a one-line summary.}
+
+## Screen / Component Requirements
+
+{What UI needs to exist, including layout, hierarchy, states, and interactions. For each surface: the implied surface from methodology step 2 + its closest repo analogue from step 3 + whether it's covered / mismatch / gap / new work from step 4.}
+
+## Interaction Details
+
+{Clicks, hovers, keyboard behavior, drag/drop, focus, transitions, gestures. Cite the analogue's existing interaction patterns when reusing; specify deliberately when diverging.}
+
+## States
+
+(omit any state the brief does not require AND the analogue does not handle)
+
+- **Empty**: {description + analogue path or "new"}
+- **Loading**: {description + analogue path or "new"}
+- **Error**: {description + analogue path or "new" — include error message tone if the codebase has a convention}
+- **Success**: {description + analogue path or "new"}
+- **Disabled**: {description + analogue path or "new"}
+- **Permission-restricted**: {description + analogue path or "new"}
+- **Mobile / narrow**: {description + breakpoint convention from analogue or "new"}
+
+## UX Risks
+
+{Where the user may get confused, stuck, or surprised. Anchored on the gaps + mismatches from methodology step 4. Each risk one line + one mitigation line.}
+
+## Visual Hierarchy
+
+{What should be most prominent, secondary, hidden, grouped, or de-emphasized. Cite analogue patterns when reusing; flag when the brief implies a hierarchy that conflicts with the codebase.}
+
+## Copy Requirements
+
+{Button labels, helper text, error messages, confirmation text, tooltips. Brief lines if the brief specifies; codebase-convention examples if not; "needs writing" entries flagged for plan mode otherwise.}
+
+## Accessibility Requirements
+
+{Keyboard navigation, focus states, contrast, labels, ARIA expectations, reduced motion. Anchored on the codebase's existing a11y patterns (search for `aria-`, `role=`, `:focus-visible`, `prefers-reduced-motion` in analogues).}
+
+## Responsiveness
+
+{Desktop / tablet / mobile behavior. Use the codebase's breakpoint convention (search tailwind.config / theme files / media queries in analogues). Flag if the brief implies breakpoints that diverge from the convention.}
+
+## Design System Fit
+
+{Existing components to prefer, patterns to reuse, styling constraints to avoid custom one-offs. For each implied surface from methodology step 2: which existing component or token set is the right base, with file paths. When no design system exists in the repo: state that clearly and instruct plan mode to discover patterns or propose an anchor.}
+
+## Acceptance Criteria
+
+{Experiential checks ON TOP OF the brief's RB-level criteria. Per-state, per-viewport, copy correctness, focus order, keyboard nav, reduced-motion, color-contrast. Each criterion concrete enough to verify in QA — no "feels right" entries.}
+
+## Plan Mode Prompt
+
+The agent should paste this verbatim into plan mode (or the agent itself should adopt it as the first instruction when entering plan mode).
+
+```
+You are about to enter plan mode for a UI/UX implementation task.
+
+First, inspect the existing UI patterns, components, routes, design-system conventions, and nearby implementations. Do not edit files yet.
+
+Specifically address before proposing any plan:
+1. {mismatch from methodology step 4 — concrete one-liner}
+2. {gap from methodology step 4 — concrete one-liner}
+3. {new-work surface from methodology step 4 — concrete one-liner}
+   (repeat 4–6 for the next most load-bearing surfaced items)
+
+Then return a plan that includes:
+- Existing patterns you found (cite file paths)
+- User flow summary
+- Components / screens likely affected
+- UI states to implement (referencing the States section of UX-REVIEW.md)
+- Accessibility considerations (referencing the Accessibility Requirements section)
+- Responsive behavior (referencing the Responsiveness section)
+- Copy or microcopy needed (referencing the Copy Requirements section)
+- Risks or ambiguous UX decisions (referencing the UX Risks section)
+- Test/QA plan (referencing the Acceptance Criteria section)
+- Proposed implementation steps
+
+Do not start coding until the plan is approved.
+```
+```
+
+---
+
+### What this review is NOT
+
+- **Not a re-derivation of the brief.** If the brief already specifies a state, the review says so in one line and moves on. The review's value is on the gaps, mismatches, and codebase-grounding — not on rewriting good content.
+- **Not an excuse to expand scope.** Stay within the brief's Goal and Non-goals. UX coverage gaps that fall OUTSIDE the brief's scope go on the deferrals list, not the acceptance criteria.
+- **Not a design tool.** This produces a planning packet, not visual designs. Where the codebase has no design system, the review surfaces that fact and routes back to the user — it does not propose one unilaterally.
+- **Not a check on existing implementations.** Use `/ritual lineage` for "what decisions shaped this code already." This review is forward-looking only.
+
+---
+
+### Failure modes to watch for
+
+- **Generic checklist filling.** Symptom: every section reads the same regardless of the brief / repo. Mitigation: methodology step 1's classification — if the output doesn't reflect what the brief actually covers vs misses, the analysis upstream wasn't done.
+- **Fabricating analogues.** Symptom: review cites file paths that don't exist. Mitigation: every file path claim must come from an actual Grep / Glob / Read result in methodology step 3.
+- **Plan-mode prompt with no surfaced findings.** Symptom: the numbered list at the top of the plan-mode prompt is a generic 10-step plan. Mitigation: methodology steps 4 and 6 — the first 3–6 items must be the actual mismatches, gaps, and new-work surfaces from step 4. If those lists were empty, the brief is unusually complete; the prompt's first three items should reflect that ("Brief is unusually complete; verify each state listed under §X exists in the codebase before extending").
+- **Scope drift.** Symptom: review proposes UI work the brief deliberately excluded under Non-goals. Mitigation: re-read Non-goals before drafting the review; deferrals list is the right destination for out-of-scope UX gaps.

package/skills/vscode/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.12",
-  "builtAt": "2026-05-14T13:31:40.197Z"
+  "cliVersion": "0.7.14",
+  "builtAt": "2026-05-15T16:06:46.162Z"
 }

package/skills/vscode/ritual/manifest.json

@@ -21,8 +21,8 @@
   },
   {
     "path": "references/build-flow.md",
-    "lines": 1519,
-    "bytes": 88142
+    "lines": 2466,
+    "bytes": 148766
   },
   {
     "path": "references/cli-output-contract.md",
@@ -53,5 +53,10 @@
     "path": "references/scoring-fallback.md",
     "lines": 126,
     "bytes": 6494
+  },
+  {
+    "path": "references/ui-ux-checklist.md",
+    "lines": 198,
+    "bytes": 12167
   }
 ]