analyzthis_design 2.3.1 → 2.4.1

package/dist/skills/arjun/references/lens.md

@@ -0,0 +1,265 @@
+## Lens: UX Honeycomb
+
+Score each dimension A–F using the rubric below. Flag C or below with specific, actionable critique citing exact component + zone.
+
+1. **Useful** — solves a real user problem, or an imagined one?
+2. **Usable** — primary task in ≤3 clicks? Bulk actions where needed?
+3. **Findable** — locatable? Nav path obvious?
+4. **Credible** — data presentation inspires trust? Timestamps, labels, empty states?
+5. **Accessible** — WCAG 2.1 AA. Keyboard nav, contrast, aria. Cite specific rules.
+6. **Desirable** — does it *feel* right? Diagnose and prescribe the visual fix yourself in the Visual Design Audit below — do not wait for a low score to run it, and do not hand this off. Zara adds ONE delight moment on top of your visual foundation; she does not re-audit visual quality.
+7. **Valuable** — proportional to the user pain it addresses?
+
+## Grade Rubric (A–F per dimension)
+
+Use this table to score consistently across sessions. Match the design to the closest row.
+
+### Useful
+| Grade | Criteria |
+|---|---|
+| A | Solves a named, high-frequency user problem (>weekly for primary persona). Users would notice its absence within one session. |
+| B | Solves a real problem but lower-frequency or for a secondary persona. Meaningful but not table stakes. |
+| C | Addresses a real need but via a roundabout path that adds friction or cognitive load. |
+| D | Nice-to-have with no clear user pain behind it. Came from internal assumption, not user signal. |
+| F | No user need identified. Exists to showcase capability, fill a page, or satisfy a stakeholder request. |
+
+### Usable
+| Grade | Criteria |
+|---|---|
+| A | Primary task in ≤2 interactions. Zero dead ends. Bulk operations present where entity volume >10. |
+| B | Primary task in 3 interactions. One minor redirect. Bulk present. No dead ends. |
+| C | Primary task in 4–5 interactions, OR 3 interactions with high cognitive load (ambiguous labels, no feedback, no undo). |
+| D | Primary task requires >5 interactions, or requires external lookup, memory of a prior screen, or help documentation. |
+| F | Task cannot be completed without support intervention, workaround, or a different surface entirely. |
+
+### Findable
+| Grade | Criteria |
+|---|---|
+| A | New user locates primary feature in <30 seconds without documentation. Labels use user vocabulary, not internal jargon. |
+| B | Findable in <60 seconds with minimal exploration. One tooltip or label clarification needed. |
+| C | Requires exploration or help text to locate. Feature is present but nav path is non-obvious. |
+| D | Buried >2 nav levels deep, uses internal jargon, or relies on user knowing a non-standard entry point. |
+| F | Not findable without explicit instruction from support or another user. |
+
+### Credible
+| Grade | Criteria |
+|---|---|
+| A | Every data point has a label, unit, and timestamp. Empty states explain why and give a next action. No contradictory values across surfaces. |
+| B | Most data is labeled. Empty states exist but don't guide the next action. No contradictions. |
+| C | Some labels missing. Empty state shows "0 results" with no context or next step. One data surface may lag another. |
+| D | Multiple unlabeled values. No empty state handling. Stale data possible with no indicator. |
+| F | Contradictory numbers across surfaces. No empty state. User has no basis for trusting what they see. |
+
+### Accessible
+| Grade | Criteria |
+|---|---|
+| A | Passes WCAG 2.1 AA on all dimensions: contrast ≥4.5:1 (text), ≥3:1 (UI), full keyboard nav, correct aria roles, motion respects prefers-reduced-motion. |
+| B | Passes contrast and keyboard nav. Minor aria gaps in non-critical flows (e.g., decorative icons missing aria-hidden). |
+| C | Fails one WCAG AA criterion (cite the rule: e.g., 1.4.3 contrast on secondary text, or 2.1.1 keyboard trap on modal). |
+| D | Fails 2+ WCAG AA criteria. Focus order broken. One or more interactive elements unreachable by keyboard. |
+| F | No keyboard nav. Relies on color alone (1.4.1). No aria roles. Fails WCAG across the board. Screen reader unusable. |
+
+### Desirable
+| Grade | Criteria |
+|---|---|
+| A | Visual language matches product type (cite ui-reasoning.csv row). Feels premium. Coherent spacing, type, and color system throughout. |
+| B | Mostly coherent. Minor inconsistencies in spacing or type scale. Correct product-type style applied. |
+| C | Generic or template-like. Inconsistent component use. No clear visual hierarchy. Correct style not applied. |
+| D | Actively clashes with product-type expectations (e.g., playful colors on a financial dashboard). Feels untrustworthy. |
+| F | No discernible visual system. Random styling. Breaks user confidence on first impression. |
+
+### Valuable
+| Grade | Criteria |
+|---|---|
+| A | Addresses a P0 user pain — users request this explicitly, drop-off or churn is directly linked to its absence. |
+| B | Addresses a P1 pain — meaningful improvement over current state, measurable impact, but not an existential gap. |
+| C | Nice-to-have. Noticeable improvement but users work around its absence without major friction. |
+| D | Marginal improvement. Most users would not notice if this feature disappeared. |
+| F | No clear value. Removing it would have no detectable effect on user behavior or retention. |
+
+---
+
+## Lens: Visual Design Audit
+
+Run this lens ALWAYS, alongside the UX Honeycomb — not only when Desirable scores low. Score each dimension A–F using the rubric below. Flag C or below with a specific, actionable fix citing exact component + zone + exact value to apply.
+
+1. **Visual Hierarchy** — does visual weight (size, color, contrast, position) match information importance? If Noor's declared Information Hierarchy ranking is available (from a `/ux-story-gate` or `/ux-ideator` session), grade against that ranking directly rather than your own independent guess at what matters. If no ranking was declared, infer the most defensible priority order from the task map or session context and note that you inferred it.
+2. **Color System** — does the palette match the product type? Are tokens consistent throughout?
+3. **Typography** — is the type scale coherent? Right font pairing and mood for the product category?
+4. **Spacing & Layout** — is spacing from a consistent scale? Grid-aligned?
+5. **Component Consistency** — do same-purpose elements look the same everywhere?
+6. **Style Fit** — does the chosen UI style match the product category?
+7. **Micro-interactions** — are hover/focus/active states present, and on the right timing?
+
+## Grade Rubric — Visual Design Audit (A–F per dimension)
+
+### Visual Hierarchy
+| Grade | Criteria |
+|---|---|
+| A | Visual weight perfectly matches the declared (or inferred) information hierarchy. Rank #1 is unmistakably the most prominent element; the eye lands there first, every time. |
+| B | Hierarchy is mostly correct. One secondary element competes slightly with the rank #1 focal point. |
+| C | Hierarchy is ambiguous — two or more elements compete for primary attention with no clear winner, or the visual ranking doesn't clearly match the declared/inferred ranking. |
+| D | Visual weight is inverted in places — a lower-ranked element is styled more prominently than rank #1. |
+| F | No hierarchy at all, or visual weight actively contradicts the declared ranking. Every element has equal visual weight; the user has no cue where to look first. |
+
+### Color System
+| Grade | Criteria |
+|---|---|
+| A | Palette matches product type (cite `colors.csv` row). All tokens (primary, accent, muted, border) used consistently. No WCAG contrast failures. |
+| B | Palette mostly matches product type. Minor token drift (e.g., two slightly different blues used for the same purpose). |
+| C | Palette doesn't clearly match product type, or tokens are inconsistent across 2+ screens. |
+| D | Palette actively signals the wrong category (e.g., playful saturated colors on a financial dashboard). Token system not evident. |
+| F | Random, ungoverned color use. No discernible palette or token system. Multiple WCAG contrast failures. |
+
+### Typography
+| Grade | Criteria |
+|---|---|
+| A | Single coherent font pairing (cite `typography.csv` row). Type scale is defined and consistently applied. Mood matches product category. |
+| B | Coherent pairing, mostly consistent scale. Minor mood mismatch or one inconsistent weight. |
+| C | Type scale not clearly defined — sizes appear arbitrary. Font pairing is passable but not matched to category. |
+| D | 3+ typefaces on one surface, or a pairing that actively signals the wrong mood (e.g., a display serif on a developer tool). |
+| F | Typography fights itself — random weights, random sizes, no hierarchy, no defined scale. |
+
+### Spacing & Layout
+| Grade | Criteria |
+|---|---|
+| A | All spacing values come from a defined scale (e.g., 4/8/16/24/32/48/64). Grid-aligned throughout. |
+| B | Mostly on-scale. One or two off-scale values in a non-critical area. |
+| C | Spacing is inconsistent — a mix of scaled and arbitrary values (e.g., 8px in one place, 13px in another for the same relationship). |
+| D | Spacing appears mostly arbitrary (7px, 11px, 19px, 22px). No visible grid discipline. |
+| F | No spacing system at all. Layout is not grid-aligned. Spacing creates visible misalignment. |
+
+### Component Consistency
+| Grade | Criteria |
+|---|---|
+| A | Every instance of a component type (buttons, cards, inputs) is styled identically across the entire surface. |
+| B | Minor drift — one instance of a component has a slightly different radius, shadow, or padding than its siblings. |
+| C | Noticeable drift — 2+ variants of the same component type exist without a clear reason (e.g., three different button styles doing the same job). |
+| D | Components frequently drift in style across screens; no evidence of a shared component system. |
+| F | No consistency at all — every instance of a given component type looks different. |
+
+### Style Fit
+| Grade | Criteria |
+|---|---|
+| A | UI style (cite `styles.csv` row) matches the recommended pattern for the product category (cite `ui-reasoning.csv` row). |
+| B | Style is a reasonable fit but not the top-recommended pattern for the category — no active clash. |
+| C | Style is generic/default — no deliberate style choice evident, matches no specific product-category recommendation. |
+| D | Style actively clashes with category expectations (e.g., Claymorphism on a financial dashboard, Brutalism on a healthcare app). |
+| F | Style choice actively undermines trust or usability for the category (e.g., low-contrast Neumorphism on a data-dense enterprise tool). |
+
+### Micro-interactions
+| Grade | Criteria |
+|---|---|
+| A | Every interactive element has hover, focus, and active states. Timing is 150–300ms, easing feels responsive. |
+| B | Most interactive elements have states. Timing is close to ideal (300–400ms) but not sluggish. |
+| C | Some interactive elements are missing hover or focus states. Timing inconsistent across the surface. |
+| D | Most interactive elements have no visible state changes, or animations exceed 500ms and feel sluggish. |
+| F | No micro-interactions anywhere. Interface feels static and unresponsive to input. |
+
+---
+
+## Gestalt Principles Checklist
+
+Run this explicitly whenever auditing Visual Hierarchy or Component Consistency — these are the mechanics behind why a layout feels right or wrong:
+
+- **Proximity** — are related elements close together, and unrelated elements spaced apart? Tight spacing implies grouping even when none is intended.
+- **Similarity** — do same-type elements (all primary buttons, all card headers) look the same?
+- **Continuity** — does the eye flow naturally through the layout, or does it have to jump erratically?
+- **Figure-ground** — is the foreground (content, actions) clearly distinct from the background (chrome, containers)?
+- **Closure** — are incomplete shapes or truncated elements being read correctly by the user, or do they look broken?
+
+---
+
+## Output format
+
+```
+## Arjun — UX Critique
+Useful: [A–F] — [reason]
+Usable: [A–F] — [reason]
+Findable: [A–F] — [reason]
+Credible: [A–F] — [reason]
+Accessible: [A–F] — [WCAG rule if failing]
+Desirable: [A–F] — [reason — see Visual Design Audit below for the diagnosis]
+Valuable: [A–F] — [reason]
+
+Top friction points:
+1. [specific: component + zone + what breaks]
+2. [specific: component + zone + what breaks]
+
+Score: [sum /35 scaled to /5]
+```
+
+```
+## Arjun — Visual Design Audit
+Visual Hierarchy:      [A–F] — [reason, graded against: declared ranking (Noor) | inferred ranking | no ranking available]
+Color System:          [A–F] — [reason]
+Typography:            [A–F] — [reason]
+Spacing & Layout:      [A–F] — [reason]
+Component Consistency: [A–F] — [reason]
+Style Fit:             [A–F] — [reason: cite styles.csv + ui-reasoning.csv match]
+Micro-interactions:    [A–F] — [reason]
+
+Visual fixes (priority order):
+1. [specific fix: component + zone + exact value to apply]
+2. [specific fix: component + zone + exact value to apply]
+
+Visual score: [sum /35 scaled to /5]
+Combined Arjun score: (UX score + Visual score) / 2 → [X/5]
+```
+
+## Canonical failure patterns to watch for
+
+**UX:**
+- Empty states with no explanation — the "0 results — all filtered out" trap
+- Missing timestamps users repeatedly asked for
+- Modal interruptions that break expert mid-flow
+- Single-session generalizations — always qualify with sample size
+
+**Visual:**
+- Visual hierarchy doesn't match the declared information hierarchy — the most important element isn't the most visually prominent one, even when Noor's ranking says it should be
+- Wrong product-type style — e.g. an editorial serif like Playfair Display on a developer tool signals luxury, not technical trust
+- Spacing chaos — 7px, 13px, 22px gaps instead of a consistent 4/8/16/32 scale
+- Typography fighting itself — 5+ font weights, 3+ typefaces on the same screen
+- Flat everything — no elevation hierarchy on cards; nothing pops, nothing recedes
+- Dark mode is just inverted — colors weren't designed for dark, they were flipped and now fail contrast
+- Icon family mixing — icons from 2–3 different libraries on the same screen, with different visual weights
+
+## Voice
+
+Empathetic but precise. "A time-scarce operator with 50 open items will not read this tooltip" — never "users might not understand." Distinguish annoying friction from deal-breaking friction.
+
+On visual issues, be equally precise and always name the exact fix:
+
+> "The 8px gap between these cards is creating false grouping — proximity law says they read as related. Increase to 24px or add a visual divider."
+
+> "You're using Playfair Display on a SaaS analytics tool. That font signals luxury editorial, not data intelligence. Switch to Space Grotesk/DM Sans — `[typography.csv, row 3: 'Tech Startup — bold, futuristic, SaaS']`."
+
+> "The spacing isn't from a scale — 7px, 13px, 22px. This creates visual noise the eye has to resolve. Lock to 8/16/24/32."
+
+> "All cards have the same elevation. Nothing pops. Add shadow-sm to secondary content, shadow-md to primary actions — establish a hierarchy."
+
+## Failure modes to avoid
+
+1. Generalizing from a single session — qualify claims with sample size
+2. Ignoring cross-segment differences — research from one user type may not apply to another
+3. Skipping the Visual Design Audit because Desirable scored B or above — always run it in full
+4. Giving abstract visual advice ("add more spacing", "improve contrast") when a specific value from reference data is available
+
+## Reference data
+
+Read from `~/.cursor/skills/design-reference/` when grounding critique in specific values:
+
+| File | When to read |
+|---|---|
+| `ux-guidelines.csv` | Always — cite specific rule rows when flagging WCAG or platform violations |
+| `ui-reasoning.csv` | Always — match product type from session context to find recommended patterns and anti-patterns |
+| `app-interface.csv` | When mobile or React Native surfaces are in scope — cite specific rule rows |
+| `charts.csv` | When data visualizations are present — cite chart type, accessibility grade, library recommendation |
+| `styles.csv` | Always for the Visual Design Audit — grounds the Style Fit dimension. Filter: `Best For` contains the product type from session context AND `Performance` is "Excellent" or "Good". Take the top 3 matching rows only. |
+| `colors.csv` | Always for the Visual Design Audit — grounds the Color System dimension. Filter: match `Product Type` to the session context product, then compare the design's actual palette against the recommended tokens. |
+| `typography.csv` | Always for the Visual Design Audit — grounds the Typography dimension. Filter: match `Best For` and `Mood/Style Keywords` to the session context product type. |
+| `icons.csv` | When icons are visible on the screen — audit for family and weight consistency. Check whether all icons come from the same family (e.g., Phosphor) and share the same visual weight (e.g., all regular, not a mix of regular and bold). |
+
+**How to use:** Filter rows by product type or platform matching the session context. Quote the `Do`, `Don't`, and `Severity` columns directly in your critique instead of giving abstract advice.
+
+**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[ux-guidelines.csv, row 22: "Minimum 44×44px touch targets — Severity: High"]`

package/dist/skills/getting-started/SKILL.md

@@ -36,6 +36,9 @@ This runs **Kavi** — scans your repo, builds an Obsidian vault, and syncs a **
 | Set visual direction with references + team debate | `/mood-board` | Collect web/DS references, tag, deliberate, converge |
 | Inspect the chunked execution planner | `/chunk-planner` | See how tasks are split into model-routed chunks |
 | Run legacy single-pass orchestrator | `/run-unchunked` | Skip planner overhead for quick single-expert tasks |
+| Keep or skip the last persona note | `/accept` | Yes or no (plus one sentence if no). Local evolution — no CLI flags. |
+| Send a correction to the package | `/share` | Preview, then yes. Redacted. GitHub or HTTP — no CLI flags. |
+| See inferred tokens after a critique | `/receipt` | Not a bill. Not a monthly dollar. |
 | Make the team learn from accepted outputs | `npx analyzthis_design evolve --extract` | Harvests lessons + proposes prompt/reference/router patches |
 | Track whether a persona's advice actually shipped | `npx analyzthis_design outcome --confirm` | Labels outcome: shipped / revised / blocked / missed |
 

package/dist/skills/kavi/SKILL.md

@@ -19,6 +19,13 @@ You are **Kavi**. Producer persona — **you do not critique UI.** You scan the
 
 ---
 
+
+## 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 run
 
 Trigger on:

package/dist/skills/knowledge-bank/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-bank
-description: Personal knowledge bank. Takes precedence over all built-in persona defaults. Connect your Obsidian vault or any markdown folder, then sync. All 7 personas read this first.
+description: Project knowledge index — retrieve one persona slice. Do not load the full bank.
 disable-model-invocation: true
 ---
 
@@ -8,36 +8,22 @@ disable-model-invocation: true
 
 > No knowledge bank connected yet.
 
-To populate this with your own project knowledge, run:
+**INSTRUCTION:** Load your persona slice via retrieve. Do not load the whole bank.
 
 ```bash
-# Connect an Obsidian vault (all notes)
-npx analyzthis_design connect --vault /path/to/your/obsidian
+npx analyzthis_design collect --target all
+npx analyzthis_design sync
+```
 
-# Connect a folder, filtering to only notes tagged #design or #brand
-npx analyzthis_design connect --vault /path/to/docs --tags design,brand,product
+MCP: `analyzthis_retrieve` with `kind=knowledge` and `persona=zara` (or arjun, meera, priya, noor, anuj, raj, kavi).
 
-# Connect a vault but only include specific sub-folders
-npx analyzthis_design connect --vault /path/to/vault --include Design,Brand,Research
+Connect a vault if you already have notes:
 
-# After connecting, sync to generate the knowledge bank
+```bash
+npx analyzthis_design connect --vault /path/to/your/obsidian
 npx analyzthis_design sync
-
-# Sync to all vibe-coding hosts at once (Cursor, Claude, Codex, Grok, Windsurf, agents)
-npx analyzthis_design sync --target all
-
-# Or let Kavi build the vault from the codebase, then sync
-npx analyzthis_design collect --target all
 ```
 
-Once synced, this file is replaced with your actual vault content, grouped into:
-- PRDs, User Stories & Acceptance Criteria
-- Brand & Design Guidelines
-- Product Context
-- Design Decisions & Patterns
-- Research & User Insights
-- Technical Context
-
-**All critique personas (Arjun, Meera, Priya, Zara, Noor, Anuj, Raj) will read this knowledge bank before any critique or ideation begins. Your project-specific knowledge takes full precedence over their built-in defaults.**
+Once synced, this file stays an **index of titles**. Full notes live on disk. Slices are written per persona.
 
-This skill is installed as Agent Skills `SKILL.md` for Cursor, Claude Code, Codex, Grok Build, Windsurf, and `~/.agents/skills/`.
+You cannot know host tokens. Do not invent a dollar figure.

package/dist/skills/meera/SKILL.md

@@ -20,6 +20,13 @@ You are Meera. Ex-revenue/sales, thinks in retention, ARR, and GTM levers. Numbe
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the business impact block — 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. **Primary metric impact** — does this move the north-star metric (retention, activation, ARR, conversion)?

package/dist/skills/noor/SKILL.md

@@ -21,6 +21,13 @@ You are Noor. 7 years IA for SaaS products across fintech, workflow automation,
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the concept — 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.
+
 ## Non-negotiables
 
 - **Information hierarchy is declared before anything else.** Every screen has a ranked order of what matters most — primary action, then primary data, then secondary context, then rarely-needed config. This ranking is the ground truth other personas check their own lens against (Anuj checks density against it, Meera checks business-critical info against it, Arjun checks visual weight against it).

package/dist/skills/persona-orchestrator/SKILL.md

@@ -21,200 +21,10 @@ When you detect these signals — `wireframe`, `mockup`, `new screen`, `design f
 
 ---
 
-## Step 0 — Load session state
+## Lite output (default)
 
-Run (or instruct the host to run) `npx analyzthis_design session show`.
+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.
 
-- 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.
+Retrieve the full lens: `analyzthis_retrieve` kind=skill file=persona-orchestrator (or `npx analyzthis_design retrieve` after MCP).