analyzthis_design 2.3.1 → 2.4.0

package/skills/persona-orchestrator/references/lens.md

@@ -0,0 +1,197 @@
+## Step 0 — Load session state
+
+Run (or instruct the host to run) `npx analyzthis_design session show`.
+
+- If a session already exists for this project: read it. Do not re-ask the user for a task map, DS tokens, or routing decision that's already recorded — this is the fix for the "Ask/Agent double spend" failure where context gets re-derived every turn.
+- If no session exists: run `npx analyzthis_design session init` to create one, then proceed to Step 1.
+
+Load `agents/session-schema.json` to know the exact shape you're reading and writing.
+
+---
+
+## Step 1 — Run ux-story-gate intake (Phases 0 – 1.5)
+
+Read `skills/ux-story-gate/SKILL.md` and run:
+- Phase 0 (PRD discovery) — skip re-deriving anything already present in session state
+- Phase 0.5 (DS/Figma discovery) — populate `ds_checklist` and `figma_node`
+- Phase 1 (task map intake gate) — populate `task_map`
+- Phase 1.5 (MoE router) — populate `routing_decision`
+
+Persist all four outputs to session state before moving on. Do not proceed to Step 2 until Phase 1's gate condition is satisfied (a confirmed task map exists).
+
+---
+
+## Step 2 — Select the execution graph (MoE subset is the default)
+
+Read `agents/router.json` and `agents/chain.json`.
+
+**Default budget is 1–2 experts.** Only run the full `default_chain` (Arjun → Meera → Priya → Zara) when one of these is explicitly true:
+- The routing decision's `problem_type` is `full_screen_review`, OR
+- The user explicitly asked for a "full critique", "full review", "design-critic", or "run all personas"
+
+Otherwise:
+- **Narrower problem type:** run only the expert(s) listed in the matching `agents/router.json` rule's `route_to`, in the order their `chain_position` implies. Never include a persona listed under that rule's `never_route_to`.
+- **Ideation / concept-generation ask:** use `ideation_chain` from `agents/chain.json` instead (Meera → Noor + Anuj → Arjun → Zara → Priya; Raj on stalemate only), matching `skills/ux-ideator/SKILL.md`.
+
+**Early DS exit (before running the chain):** if `ds_checklist` has any item marked "at risk" from Phase 0.5, and the ask is not itself a DS/brand remediation ask, stop the graph at the DS Gate remediation path — run only DS Gate checks + Arjun in `arjun_color_system_only` scope. Do not run Meera, Priya, or Zara until the DS Gate clears, unless the user explicitly overrides with "run everything anyway."
+
+**Parallel execution:** check each persona's manifest for `parallel_safe_with`. If two selected experts list each other there (e.g. Meera and Priya), run them independently — do not require one's output before starting the other. Only sequence experts that actually need a prior handoff.
+
+Announce the selected graph and why it's smaller than the full chain, one line: *"Running [chain name] with [persona list] (budget: N) — excluding [excluded personas] per the router. Full chain not run because [reason]."*
+
+---
+
+## Step 3 — Execute adversarial deliberation (v1.19)
+
+Read `deliberation-protocol` from your host skills dir (sibling preferred), e.g. `~/.cursor/skills/deliberation-protocol/SKILL.md`, `~/.claude/skills/deliberation-protocol/SKILL.md`, `~/.grok/skills/deliberation-protocol/SKILL.md`, `~/.agents/skills/deliberation-protocol/SKILL.md`, or legacy `~/.claude/commands/deliberation-protocol.md` **first**. Personas **debate** — they do not pass generic handoff documents.
+
+**Preferred (CLI):** `npx analyzthis_design run --task "..." [--full] [--satisfaction 0.4] [--max-rounds 3]` — enforces parallel groups, objection rounds, Raj escalation, and writes `deliberation.round_log` to session.
+
+**Chat workflow** when not using CLI:
+
+1. Build **context pack** from session: `task_map`, `ds_checklist`, `information_hierarchy`, knowledge bank excerpts
+2. Run **deliberation groups** from `agents/chain.json` → `deliberation_groups` (critique / ideation / lite)
+3. **Review mode (rounds 0..N-1):** each persona reads prior outputs, raises grounded objections, asks contextual questions. Default `accepts_prior: false`. Output deliberation JSON block per `agents/deliberation-schema.json`
+4. **Parallel pairs:** Noor∥Anuj, Meera∥Priya — critique each other's claims in the same round
+5. **Produce mode (final round):** full output schema only after objections resolve or Raj rules
+6. After each persona: append to `persona_outputs`, update `digest.prior_scores`, append to `deliberation.round_log`
+7. **Raj** on stalemate: 2+ blocking objections, repeated claims, or round >= `escalate_to_raj_after_round`
+
+Forbidden in review rounds: generic handoff lines without citing a specific prior claim; rewriting full wireframes/critiques before deliberation closes.
+
+For reference data: `npx analyzthis_design retrieve --file <csv> --column <col> --keywords <a,b>`
+
+Legacy sequential mode: `npx analyzthis_design run --no-deliberate` or skip deliberation-protocol in chat (not recommended).
+
+---
+
+## Step 4 — Hard gates
+
+Run in this order, after the chain completes:
+
+1. **DS Gate** — re-check the DS Token Checklist from Phase 0.5. If any item is still "at risk," this blocks a SHIP verdict regardless of composite score.
+2. **Information Hierarchy Gate** — read `skills/design-critic/SKILL.md`'s Information Hierarchy Gate section and run it against Arjun's Visual Hierarchy grade and Meera's Hierarchy check (only if both ran).
+3. **Verify Gate** — run `ux-story-gate` Phase 4.5 (browser automation) against the primary task. Record `verify_results` in session state.
+
+Any gate failure is inserted into the Top 3 actionable changes automatically, same as the Information Hierarchy Gate rule in `design-critic`.
+
+---
+
+## Step 5 — Synthesize verdict
+
+Produce the Task × Finding table (format from `ux-story-gate` Phase 5) or the Composite Score block (format from `design-critic` Phase 5), depending on which graph ran. Include:
+
+```
+## Orchestrator Run Summary
+Graph:            [default_chain / ideation_chain / MoE subset: persona list]
+Experts run:      [N] (budget) — [persona list]
+DS Gate:          [PASS / FAIL — item(s) at risk]
+Hierarchy Gate:   [PASS / FAIL]
+Verify Gate:      [pass / fail / not_run]
+Verdict:          [SHIP / REVISE / BLOCK]
+Mode:             [assess_only / build_approved]
+Est. tokens:      [input/output estimate — see metrics in session state]
+```
+
+Update `session-state.json` (`metrics`): `llm_calls`, `experts_run`, `input_tokens_est`, `output_tokens_est`, `cache_hits`, `mode`.
+
+If any gate failed or the verdict is BLOCK, escalate to Raj per `design-critic`'s BLOCK escalation rules.
+
+**Delta re-evaluation (mandatory on any follow-up after REVISE):** when the user applies changes and asks for a re-check, do NOT re-run the full graph. Read `session-state.json`'s prior `persona_outputs` and Top 3 actionable changes, then run only the persona(s) assigned to those Top 3 items, per `skills/design-critic/SKILL.md`'s Re-evaluation Protocol. Update only the affected `digest.prior_scores` entries and re-check the Information Hierarchy Gate. This is not optional — re-running the full chain on every follow-up is the token-waste failure this system exists to prevent.
+
+---
+
+## Step 6 — Respect assess-only mode
+
+Run `ux-story-gate` Phase 5.5. If `mode: assess_only`, stop here — do not write or edit code. If `mode: build_approved`, proceed to implement the P0/P1 fixes named in the synthesis.
+
+---
+
+## Step 6.5 — Capture user corrections and outcomes (v1.16 / v1.21)
+
+When the user is **unhappy** with a persona's output or **rewrites/corrects** it, record that signal so future training can learn from mistakes:
+
+```bash
+npx analyzthis_design feedback record --persona arjun --rating 2 \
+  --comment "What was wrong" \
+  --correction "What they wanted instead" \
+  --tags wrong_hierarchy,invented_tokens
+```
+
+Or in one step when rejecting:
+
+```bash
+npx analyzthis_design session accept --persona arjun --reject \
+  --comment "..." --correction "..." --rating 2 --tags off_brief
+```
+
+Suggest this when the user says things like *"that's not what I meant,"* *"use our tokens,"* or *"the hierarchy is wrong."* Tags hint: `wrong_hierarchy`, `invented_tokens`, `missed_ds`, `too_verbose`, `bad_ia`, `off_brief`.
+
+List or export later: `feedback list`, `feedback export --persona arjun --all`.
+
+**Track whether the advice actually shipped.** After the user implements changes, confirm the outcome so the evolution loop can learn:
+
+```bash
+npx analyzthis_design outcome --confirm --persona arjun --result shipped
+# or: revised, blocked_correctly, missed
+```
+
+**Default execution is chunked (v2.0).** `npx analyzthis_design run --task "..."` now uses a frontier planner + cheap chunk models. Use `/run-unchunked` or `npx analyzthis_design run-unchunked` only when you explicitly want the legacy single-pass deliberation chain.
+
+**Set visual direction with the team.** Use `/mood-board` when the user wants references and a team-deliberated direction:
+
+```bash
+npx analyzthis_design moodboard create --task "B2B fintech dashboard, trustworthy, high-contrast" --auto
+npx analyzthis_design moodboard critique --board <boardId>
+```
+
+References are tagged, design-system patterns are pulled, and Arjun/Meera/Priya/Zara/Noor deliberate with Honeycomb scoring until consensus.
+
+**Evolve the team.** Periodically (e.g., weekly), run:
+
+```bash
+npx analyzthis_design evolve --extract --dry-run   # preview proposed patches
+npx analyzthis_design evolve --extract             # write patch files for review
+npx analyzthis_design evolve --apply <patchId> --dry-run   # preview a patch
+npx analyzthis_design evolve --apply <patchId>    # apply after review
+```
+
+This harvests accepted outputs + confirmed outcomes, extracts lessons into `~/.analyzthis_design/lessons/`, and proposes patches to:
+- persona SKILL.md / cards (new canonical failure patterns),
+- `skills/design-reference/*.csv` rows (new product-type guidance),
+- `agents/router.json` rules (task_type → best-performing expert).
+
+Patches are **dry-run by default** and require human review before apply.
+
+**Share with maintainers (opt-in):** after recording, suggest `npx analyzthis_design feedback submit --yes` so anonymized corrections help improve personas for everyone. Preview first with `--dry-run`.
+
+---
+
+## What this skill is not
+
+- **Not a persona.** It has no design opinion — it routes to the ones that do.
+- **Not a replacement for `ux-story-gate` or `design-critic`.** It calls them; it doesn't duplicate their logic.
+- **Not a code generator by default.** Respects assess-only mode like every other skill in this system.
+
+---
+
+## Files this depends on
+
+- `agents/router.json` — MoE routing rules
+- `agents/chain.json` — default and ideation chains, deliberation_groups, gate ordering, token caps
+- `agents/deliberation-schema.json` — objection/satisfaction output contract
+- `deliberation-protocol` skill — adversarial review rules (v1.19); host path e.g. `~/.claude/skills/deliberation-protocol/SKILL.md`
+- `agents/session-schema.json` — session state shape, including `digest` and `metrics`
+- `agents/manifests/*.json` — per-persona allowed/forbidden jobs, hard gates, `system_card`, `tier`, `max_output_tokens`
+- `agents/cards/*.md` — short persona system prompts used by default instead of full SKILL.md
+- `skills/ux-story-gate/SKILL.md` — intake phases 0 – 1.5, 4.5, 5.5
+- `skills/design-critic/SKILL.md` — chain handoff format, Information Hierarchy Gate, BLOCK escalation, Re-evaluation Protocol
+- `npx analyzthis_design session init|show|reset` — session state CLI
+- `npx analyzthis_design research --url|--query` — writes `web-context.md` into the session; also load this file alongside the knowledge bank before Step 1. In Cursor/Claude, if the CLI research stub is empty, use WebSearch/WebFetch/Figma MCP and append the result to the same `web-context.md` path.
+
+## Efficiency defaults
+
+- Default to the **MoE subset**, not the full chain — see Step 2.
+- Default to **cards + lite schema**, not full SKILL.md + deep schema — see Step 3.
+- Default to **delta re-evaluation** on follow-ups, not a full re-run — see Step 5.
+- Skip Phase 4.5 browser verify when `mode: assess_only` and no running URL is available; record `verify_results.primary_task: "not_run"` rather than skipping silently.

package/skills/priya/SKILL.md

@@ -20,6 +20,13 @@ You are Priya. Senior full-stack engineer, 8+ years in complex SaaS. Blunt, prec
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the feasibility analysis — do not edit code.
 
+
+## Lite output (default)
+
+Verdict or one moment. Top three fixes (or one delight). One evidence line.
+Use the full output schema below only if the user says expand.
+You cannot know host tokens. Do not invent a dollar figure.
+
 ## Lens
 
 1. **Technical complexity** — CRUD vs state machine vs new infrastructure

package/skills/raj/SKILL.md

@@ -22,6 +22,13 @@ You are Raj. 10+ years product strategy across SaaS, marketplace, and workflow a
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the arbitration verdict — do not edit code.
 
+
+## Lite output (default)
+
+Verdict or one moment. Top three fixes (or one delight). One evidence line.
+Use the full output schema below only if the user says expand.
+You cannot know host tokens. Do not invent a dollar figure.
+
 ## When to activate (Stalemate Protocol)
 
 ONLY when one of these conditions is met:

package/skills/receipt/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: receipt
+description: Show inferred token spend for this project's last slash and MCP turns. Not a bill. Use after a critique when you want to see tokens-per-verdict.
+disable-model-invocation: true
+---
+
+# Receipt
+
+You cannot know Claude’s real usage from slash alone. Do not invent a dollar figure.
+
+## What to do
+
+1. Run `npx analyzthis_design receipt` in this project, or call the MCP tool `analyzthis_receipt`.
+2. Report the printed inferred tokens and tokens-per-verdict exactly.
+3. Label them **inferred**, never verified, never a monthly dollar.
+
+If there is no session yet: `npx analyzthis_design session init`, then run a critique, then receipt.

package/skills/ux-story-gate/SKILL.md

@@ -11,343 +11,10 @@ The personas (Noor, Anuj, Arjun) are the rooms. This is the front door.
 
 ---
 
-## Phase 0 — PRD Discovery (runs before anything else)
+## Lite output (default)
 
-Before asking the user for anything, scan for existing context in this order:
+Verdict or one moment. Top three fixes (or one delight). One evidence line.
+Expand the full schema only if the user says expand.
+Call retrieve for the rest of this skill (kind=skill). You cannot know host tokens. Do not invent a dollar figure.
 
-### 0a — Check the knowledge bank
-
-Read the knowledge-bank skill from your host's skills dir (sibling `knowledge-bank` preferred), e.g. `~/.cursor/skills/knowledge-bank/SKILL.md`, `~/.claude/skills/knowledge-bank/SKILL.md`, `~/.grok/skills/knowledge-bank/SKILL.md`, `~/.agents/skills/knowledge-bank/SKILL.md`, or legacy `~/.claude/commands/knowledge-bank.md`.
-
-Look for sections containing:
-- User stories (`As a [persona], I want to...`, `Given / When / Then`)
-- Acceptance criteria, PRD sections, requirements
-- Named user personas with roles and tasks
-- Epics, features, job-to-be-done statements
-- Any section titled or tagged: PRD, requirements, user-stories, specs, product-context
-
-If the knowledge bank contains relevant content for the screen being reviewed: **extract it into a draft task map** (see format in Phase 1). Mark each entry with `[source: knowledge-bank]`.
-
-### 0b — Scan the current repo
-
-Look for files matching these patterns in the project root and common sub-directories:
-- `PRD*.md`, `*prd*.md`, `*requirements*.md`, `*user-stories*.md`, `*specs*.md`
-- `docs/**/*.md`, `specs/**/*.md`, `requirements/**/*.md`, `planning/**/*.md`
-- Any `.md` file containing keywords: "user story", "acceptance criteria", "as a [role]", "given when then", "persona", "job to be done", "JTBD", "done when", "fails when"
-
-Read all matching files. Extract task-relevant content. Mark each entry with `[source: filename]`.
-
-### 0c — Build a draft task map from discovered content
-
-From everything found in 0a and 0b, construct a draft task map using the format:
-
-```
-PERSONA:    [named role from the PRD / story]
-TASK:       [verb + object — extracted or inferred from acceptance criteria]
-FREQUENCY:  [daily / weekly / one-time / first-time-only — from PRD or inferred]
-DONE WHEN:  [success condition from acceptance criteria, or inferred]
-FAILS WHEN: [failure condition from acceptance criteria, or inferred]
-SOURCE:     [knowledge-bank / filename]
-```
-
-Present the draft task map to the user:
-
-> "I found the following tasks relevant to this screen in [sources]. Does this capture what the screen needs to support? Add, remove, or correct anything before I proceed — I'll run the critique against your confirmed version, not my guess."
-
-If the user confirms: proceed to Phase 1 with the confirmed task map.
-If the user corrects: apply corrections, confirm again, then proceed.
-
-### 0d — If no PRD context found anywhere
-
-If no relevant content is found in the knowledge bank or the repo, switch to the manual intake mode from Phase 1 below.
-
-If the user has a vault but hasn't synced it:
-
-> "I don't see a knowledge bank connected. If you have PRDs or user stories in an Obsidian vault or docs folder, run `npx analyzthis_design connect --vault /path/to/vault && npx analyzthis_design sync` to make them available. I'll read them automatically next time.
-> For now — tell me the tasks this screen needs to support:"
-
----
-
-## Phase 0.5 — Design System & Figma Discovery (GATE)
-
-**Purpose:** No persona touches brand color, contrast, or component styling before the design system is on the table. This is the fix for personas inventing hex values or patching contrast with `!important`.
-
-### 0.5a — Figma discovery (if a Figma URL is present in the ask)
-
-If the user shared a `figma.com` URL, this is **mandatory before any persona speaks**:
-1. Call the Figma MCP `get_screenshot` for the linked node — this is the visual ground truth.
-2. Call the Figma MCP `get_variable_defs` for the linked node — this is the token ground truth (colors, type scale, spacing).
-3. Write both to session state (`figma_node.url`, `figma_node.confirmed: true`) via `npx analyzthis_design session init` / the session file directly.
-
-If no Figma URL is present, proceed without this step and note `figma_node.confirmed: false`.
-
-### 0.5b — Brand / design-system tokens
-
-Read the `## Brand & Design Guidelines` section of the knowledge bank (`~/.cursor/skills/knowledge-bank/SKILL.md` or platform equivalent).
-
-- **If found:** extract the token set (colors, type scale, spacing scale, component library) into the DS Token Checklist below.
-- **If missing:** flag it and ask the user directly:
-
-> "I don't see brand or design-system tokens in the knowledge bank. Before I let any persona touch color, spacing, or component choices, I need your token source — a Figma variables link, a design-tokens file, or a short list of approved hex/spacing values. Without this, Arjun's Color System and Style Fit grades will be marked unverified."
-
-### 0.5c — DS Token Checklist (exit criteria for this phase)
-
-Output before proceeding, and re-check it after any visual fix is proposed:
-
-```
-## DS Token Checklist
-No invented hex / no !important overrides:     [ ] confirmed / [ ] at risk
-Kit components preferred over custom CSS:      [ ] confirmed / [ ] at risk
-Light/dark surfaces sourced from tokens only:  [ ] confirmed / [ ] at risk
-Contrast checked against WCAG:                 [cite ux-guidelines row, or "not yet checked"]
-```
-
-Persist this to `session-state.json` (`ds_checklist`). Any item left "at risk" travels with the task map into Phase 4 routing — it forces the **DS Gate** route from Phase 1.5, not a direct Zara or Noor-alone pass.
-
----
-
-## Phase 1 — Task Map Intake (GATE)
-
-**Used when Phase 0 finds no context, or to supplement what was found.**
-
-A valid task map must contain, for each task:
-
-```
-PERSONA:    [named persona — Retailer Admin / Media Sales / Ad Ops Manager / etc.]
-TASK:       [verb + object — "Import a Google audience by ID"]
-FREQUENCY:  [daily / weekly / one-time / first-time-only]
-DONE WHEN:  [the user knows the task succeeded because...]
-FAILS WHEN: [the user knows something went wrong because...]
-```
-
-**If a valid task map is present (from Phase 0 or user input):** proceed to Phase 2.
-
-**If no task map is present:** do NOT proceed. Ask:
-
-> "Before I run any critique, I need the task map for this screen. For each user task this screen should support, tell me:
-> - Which persona? (e.g. Retailer Admin, Media Sales)
-> - What task? (verb + object)
-> - How often? (daily / weekly / one-time)
-> - Done when? (one sentence)
-> - Fails when? (one sentence)
->
-> Once I have these, I'll route to the right personas grounded in your tasks — not abstract principles."
-
-Never assume a task map. Never infer tasks from the screen description alone. If PRD context was found but incomplete, ask only for the missing fields — not the whole form.
-
----
-
-## Phase 1.5 — Problem-Type Router (MoE)
-
-**Purpose:** Pick the right expert(s) for the problem, not the loudest persona for the screen type. This is a Mixture-of-Experts router: it classifies the ask into a problem type, then reads `agents/router.json` to select which personas run and which are explicitly excluded.
-
-1. Classify the confirmed task map + DS Token Checklist into one or more problem types using the table below (mirrors `agents/router.json`):
-
-| Problem signal | Route to | Never route to |
-|---|---|---|
-| Structure / IA / nested UI | **Noor** | Zara |
-| UX friction / accessibility / responsive | **Arjun** | Zara for contrast fixes |
-| Brand / tokens / contrast / DS compliance | **DS Gate** then Arjun Color System only | Zara, Noor alone |
-| Business priority / metric alignment | **Meera** | — |
-| Build size / modal vs wizard | **Priya** | — |
-| Delight / onboarding peak moment | **Zara** (only after DS Gate passes) | — |
-| Daily-use density / bulk actions | **Anuj** (only if Frequency = daily/weekly) | — |
-| Stalemate / BLOCK | **Raj** | — |
-
-2. Write the routing decision to `session-state.json` (`routing_decision: { problem_type, experts, reason }`) — e.g. via the session file, so later phases and persona hand-offs don't re-derive it.
-3. Announce the decision in one line per persona:
-
-> "Routing to **Arjun** — Task 2 has an unresolved contrast risk (DS Gate item 'at risk'). **Zara excluded** — delight is out of scope until the DS Gate clears."
-
-If any DS Token Checklist item is "at risk," the DS Gate route takes precedence over any other route for that task — no persona touches color/contrast/tokens until it clears. This also means: **do not run Meera, Priya, or Zara yet** — stop at DS Gate remediation + Arjun's Color System dimension only, and resume the rest of the chain once the checklist clears (or the user explicitly says to proceed anyway).
-
-**Expert budget:** default to the smallest expert set that covers the routed problem type(s) — usually 1–2 personas. Only expand to the full Noor+Anuj+Arjun+Meera+Zara routing table in Phase 4 below when the ask is a genuine full-screen review, not a narrow question.
-
----
-
-## Phase 2 — Field Veto Pass
-
-**Purpose:** Catch fields and elements that exist without a task owner before personas evaluate them.
-
-Scan the screen description for every distinct field, button, label, and section. For each, run the veto test:
-
-> *"Which persona, in which task from the confirmed task map, would fail if this element didn't exist?"*
-
-Output: a Field Veto Table.
-
-```
-| Element          | Task it serves     | Verdict         |
-|------------------|--------------------|-----------------|
-| Cohort Name      | Task 1, Task 2     | ✅ Keep         |
-| Tags (max 3)     | None               | ❌ Cut / Justify|
-| Audience ID      | Task 2             | ✅ Keep         |
-| Description      | [task unclear]     | ⚠️ Clarify      |
-```
-
-Three verdicts only:
-- **✅ Keep** — maps to at least one task
-- **❌ Cut** — no task owner; recommend removal before personas run
-- **⚠️ Clarify** — ambiguous; ask the user to confirm which task this serves before proceeding
-
-Do not remove fields. Flag and ask. User confirms. Then proceed.
-
----
-
-## Phase 3 — Scale & States Declaration
-
-**Purpose:** Force the two questions most commonly skipped in story-writing.
-
-**Scale question (required for any screen with a list or table):**
-
-> "At how many rows does this screen need to work? (e.g. 10 / 100 / 1000+)"
-> "Does the list need sorting? If yes, which columns and what's the default order?"
-> "Does the list need filtering? If yes, which filters, and should selected state persist across sessions?"
-
-If scale is not declared, flag: *"Scale not specified. Personas will note this as unverified and may give incomplete Usable scores."*
-
-**States checklist (required for every screen):**
-
-Check the input for all four states. Flag any that are missing before personas run.
-
-```
-EMPTY STATE:   [what the user sees at zero data — does it teach the next action?]
-ERROR STATE:   [what the user sees when input is wrong — is recovery actionable?]
-LOADING STATE: [skeleton / spinner / nothing — is perceived latency acceptable?]
-EDGE STATE:    [what the user sees at max scale / stale data / partial data]
-```
-
-If a state is missing: *"[State] not defined. Arjun will flag this as untested — defining it now will produce a more accurate Credible score."*
-
-Can proceed with undefined states, but mark them explicitly as gaps that will surface in persona output.
-
----
-
-## Phase 4 — Persona Routing
-
-**Purpose:** Select the right personas for the task map, not for the screen type. This refines the Phase 1.5 MoE decision down to per-task assignments.
-
-Read the confirmed task map and route based on task characteristics:
-
-| Task characteristic | Route to |
-|---|---|
-| Any creation / form / IA structure task | Noor |
-| Any daily-use / list / scan / sort / filter task (Frequency = daily or weekly) | Anuj |
-| Any task with a named error / empty / loading state risk | Arjun |
-| Any task involving pricing, access control, or business rules | Flag for Meera |
-| Any task involving a first-time / onboarding experience | Flag for Zara |
-
-Always route to at least **Noor + Arjun**. Add **Anuj** whenever any task has Frequency = daily or weekly.
-
-Announce routing decisions — one line each:
-
-> "Routing to **Noor** — Tasks 1 and 2 are creation flows with IA structure decisions.
-> Routing to **Anuj** — Tasks 4 and 5 are daily-use list tasks at 100+ rows.
-> Routing to **Arjun** — Task 2 has an unrecovered error state risk; Task 1 has an undefined empty state."
-
-Each persona receives:
-1. The confirmed task map (not the raw screen description)
-2. The Field Veto Table with verdicts
-3. The Scale declaration
-4. The States checklist with gaps flagged
-5. The instruction: *"Evaluate only against the tasks in this map. Do not evaluate against abstract principles unless they directly explain a task failure."*
-
----
-
-## Phase 4.5 — Verify Gate (Browser Automation)
-
-**Purpose:** No screen is declared done on the strength of a critique alone. This is the fix for bugs that personas miss and users catch — the critique must be checked against a running browser, not just read off a screenshot.
-
-Run this after the persona chain completes, before Phase 5 synthesis:
-
-1. **Navigate** to the screen under review (`browser_navigate`).
-2. **Snapshot** the page (`browser_snapshot`) to confirm structure matches what personas critiqued.
-3. **Click through the primary task** from the confirmed task map — the highest-priority task, end to end (`browser_click`, `browser_type`, etc.).
-4. **Screenshot** at both mobile and desktop viewports.
-5. Record the result in `session-state.json` (`verify_results: { primary_task: "pass" | "fail", screenshots: [...] }`).
-
-**FAIL conditions — do not declare the screen done if any of these are true:**
-- The primary interaction is broken (e.g. state cycling incorrectly, stuck loading, dead click)
-- Modal/dialog roles are missing or focus is not trapped
-- Contrast visibly fails at either viewport despite the DS Gate marking it "confirmed"
-
-If verification fails, loop back: flag the specific broken step, do not proceed to Phase 5 synthesis until it's fixed or explicitly deferred by the user.
-
-If browser tools are unavailable in the current environment, state this explicitly and mark `verify_results.primary_task: "not_run"` — do not silently skip the gate.
-
-**Skip condition (still explicit, not silent):** if `mode: assess_only` (see Phase 5.5) and no running URL is available to navigate to, do not attempt this phase — record `verify_results.primary_task: "not_run"` with the reason "assess_only, no URL" and move to Phase 5. This avoids burning a browser-automation pass on a proposal nobody asked to be built yet.
-
----
-
-## Phase 5 — Synthesis Output
-
-After all routed personas complete their critiques, synthesise into a Task × Finding table:
-
-```
-| Task | Status | Noor | Anuj | Arjun | Priority |
-|------|--------|------|------|-------|----------|
-| Task 1: Create My Cohort | ❌ | Paths not built | No bulk import | Empty state undefined | P0 |
-| Task 2: Import by ID     | ⚠️ | —  | — | No format hint, silent fail | P0 |
-| Task 3: Set pricing      | ✅ | Remove asterisks | — | — | P1 |
-| Task 4: Daily list scan  | ❌ | — | 6 columns missing, no sort | Credible D at 100+ rows | P0 |
-| Task 5: Filter / persist | ❌ | — | No persisted state | — | P0 |
-```
-
-Priority is set by the gate, not by any persona:
-- **P0** — task cannot be completed at all, or fails on first attempt
-- **P1** — task can be completed but with significant friction
-- **P2** — task completes but with minor friction or missing polish
-
-End with a build-ready verdict:
-
-> *"[N] tasks are P0 — these must be resolved before the screen ships. [N] tasks are P1 — these should ship in the same sprint. [N] tasks are P2 — these can follow."*
-
----
-
-## Phase 5.5 — Assess-Only Mode
-
-**Purpose:** Fix the "Ask/Agent double spend" failure — a user who asked for an assessment should not wake up to code changes they didn't approve.
-
-Check the original ask for intent before writing or editing any code:
-
-- If the user's language was **assess / propose / critique / review / what's wrong / evaluate**: this is `assess_only` mode. Output stops at the Phase 5 synthesis and the proposed fixes. Set `session-state.json` (`mode: "assess_only"`). Do not touch code.
-- If the user's language was **build / implement / apply / fix it / ship it**: this is `build_approved` mode. Proceed to implement the P0/P1 fixes from the synthesis table. Set `mode: "build_approved"`.
-- If intent is ambiguous, default to `assess_only` and ask: *"I've completed the assessment above — want me to implement the P0 fixes now, or would you like to review the proposal first?"*
-
-This gate applies to every persona downstream, not just the gate itself — restate `mode` when handing off to `design-critic` or any individual persona.
-
----
-
-## Trigger phrases
-
-Use this skill when you see:
-- "Review this screen" / "What's wrong with this?" / "Critique this"
-- "Are we building this right?"
-- "Does this match the user task?"
-- "Run the personas on this"
-- "Evaluate this before we build"
-- Any Figma link, screenshot, or screen description shared without a task map
-
----
-
-## What this skill is not
-
-- **Not a persona.** No design opinion of its own.
-- **Not a PRD generator.** Does not write stories. Validates that stories were written correctly before design evaluation begins.
-- **Not a replacement for the personas.** Noor, Anuj, and Arjun still run in full. This ensures they run on the right input.
-- **Not optional.** If someone invokes `/noor`, `/anuj`, or `/arjun` directly without a task map, they bypass the gate. Use this as the entry point for any screen evaluation. For a fully agentic run (routing + chain + gates + session state in one call), prefer `/persona-orchestrator`.
-
----
-
-## Persona skills this depends on
-
-- `~/.cursor/skills/noor/SKILL.md`
-- `~/.cursor/skills/anuj/SKILL.md`
-- `~/.cursor/skills/arjun/SKILL.md`
-- `~/.cursor/skills/knowledge-bank/SKILL.md` (for Phase 0 PRD discovery)
-
-## Agentic layer this depends on
-
-- `agents/router.json` — MoE routing table used in Phase 1.5
-- `agents/session-schema.json` — shape of the session state written throughout this gate
-- `npx analyzthis_design session init|show|reset` — CLI for reading/writing session state between turns
-- For a fully orchestrated run instead of using this gate directly, use `skills/persona-orchestrator/SKILL.md`
+Retrieve the full lens: `analyzthis_retrieve` kind=skill file=ux-story-gate (or `npx analyzthis_design retrieve` after MCP).