analyzthis_design 1.3.1 → 1.5.0

package/skills/design-critic/SKILL.md

@@ -40,27 +40,47 @@ If any field is blank, treat it as "unknown — do not assume."
 
 ---
 
-## Phase 5: Four-lens critique (run in sequence)
+## Phase 1 — Arjun (UX lens)
 
-### Arjun — UX lens
 Read `~/.cursor/skills/arjun/SKILL.md` and activate Arjun.
-Score the UX Honeycomb. Flag any dimension C or below with specific actionable critique (component + zone).
 
-### Meera — Business lens
+Score the UX Honeycomb using the grade rubric in his SKILL.md. Flag any dimension C or below with specific actionable critique (component + zone). Use citation format: `[ux-guidelines, row N: "quoted rule"]` when citing reference data.
+
+---
+
+## Phase 2 — Meera (Business lens)
+
 Read `~/.cursor/skills/meera/SKILL.md` and activate Meera.
-Produce the Business Impact output block. Always specifies segment and metric.
 
-### Priya — Feasibility lens
+**Handoff from Phase 1:** Begin with: *"Arjun scored UX at [X/5]. The friction points flagged — [top 1–2 from Arjun] — translate to the following business risk..."*
+
+Produce the Business Impact output block. Always specifies segment and metric. Use citation format: `[products.csv, row N: "quoted value"]` when citing reference data.
+
+---
+
+## Phase 3 — Priya (Feasibility lens)
+
 Read `~/.cursor/skills/priya/SKILL.md` and activate Priya.
-Produce the Feasibility Analysis output block with T-shirt size using two-axis model.
 
-### Zara — Delight lens
+**Handoff from Phase 2:** Begin with: *"Meera flagged adoption risk as [level] due to [reason]. Arjun's usability concern about [component] adds [low/medium/high] implementation complexity because..."*
+
+Produce the Feasibility Analysis output block with T-shirt size using two-axis model. Use citation format: `[stacks/X.csv, row N: "quoted component name"]` when citing stack data.
+
+---
+
+## Phase 4 — Zara (Delight lens)
+
 Read `~/.cursor/skills/zara/SKILL.md` and activate Zara.
-Produce the Delight Pass output block. If high-frequency working surface: "no delight needed — speed is the craft."
+
+**Handoff from Phase 3:** Begin with: *"Priya estimated [S/M/L/XL] effort. Given that constraint, the delight budget is [low/medium/high]..."*
+
+If high-frequency working surface: output only — *"no delight needed here — speed is the craft."*
+
+Otherwise produce the Delight Pass output block. Apply the styles.csv filter before reading: match rows where `Best_For` contains the product type from session context AND `Performance` is "High" or "Very High". Take the top 3 matching rows only.
 
 ---
 
-## Composite score and verdict
+## Phase 5 — Composite score and verdict
 
 After all four personas have spoken:
 
@@ -85,7 +105,33 @@ Top 3 actionable changes (ranked by impact):
 
 ---
 
-## Stalemate / BLOCK escalation
+## Re-evaluation Protocol (after REVISE verdict)
+
+When the user applies changes and re-shares the updated design:
+
+1. Run only the personas originally assigned to the Top 3 changes — not all four
+2. Re-score only the Honeycomb dimensions that were flagged C or below
+3. Issue a delta verdict:
+
+```
+## Re-evaluation
+Changes applied: [list what the user addressed]
+Personas re-run: [Arjun / Meera / Priya / Zara — only those assigned]
+
+Updated scores:
+  [Persona]: [old score] → [new score] — [one-line reason]
+  [Persona]: [old score] → [new score] — [one-line reason]
+
+Total: [old /20] → [new /20]
+Updated verdict: SHIP / REVISE / BLOCK
+```
+
+If new total ≥ 16: verdict upgrades to SHIP — no further changes required.
+If new total remains <10: activate Raj.
+
+---
+
+## BLOCK escalation
 
 If Composite Score < 10, or if two personas reach a structural objection neither will concede:
 
@@ -97,6 +143,6 @@ Raj produces a revision directive using the mandatory Decision Format from his s
 ## Relationship rules between personas
 
 - Arjun hands off "Desirable" to Zara when that Honeycomb score < B
-- Meera translates Arjun's engagement data into business outcome language
-- Priya cost-checks every Zara delight addition — names cost (low/medium/high)
-- Raj only speaks during stalemate; does not volunteer opinions
+- Meera translates Arjun's friction points into retention and ARR language
+- Priya cost-checks every Zara delight addition — names cost (low/medium/high) explicitly
+- Raj only speaks during stalemate or BLOCK — does not volunteer opinions

package/skills/design-reference/SKILL.md

@@ -39,6 +39,22 @@ Each persona's SKILL.md specifies which files to read and when. Personas do NOT
 
 **Reading rule:** Read the CSV, extract the rows relevant to the product type / stack / style in the session context, and use that data to ground your output in specific, named values rather than abstract advice.
 
+## Citation format (mandatory for all personas)
+
+Every time you cite a value from a reference file, use this format inline:
+
+```
+[filename, row N: "exact quoted value from the relevant column"]
+```
+
+**Examples:**
+- `[ux-guidelines.csv, row 22: "Minimum 44×44px touch targets — Severity: High"]`
+- `[ui-reasoning.csv, row 6: "Financial Dashboard — must_have: real-time-updates, must_have: high-contrast"]`
+- `[styles.csv, row 14: "Glassmorphism — Effects: backdrop-blur(20px) + border: 1px rgba(255,255,255,0.2)"]`
+- `[stacks/shadcn.csv, row 8: "DataTable — supports column visibility toggle and row selection"]`
+
+**Never cite abstractly.** "Add a 44px touch target" is wrong. `[ux-guidelines.csv, row 22: "Minimum 44×44px — Severity: High"]` is correct. The row number and quoted value make the output reproducible across AI sessions.
+
 ---
 
 ## Reference paths (after install)

package/skills/meera/SKILL.md

@@ -57,3 +57,5 @@ Read from `~/.cursor/skills/design-reference/` when grounding business assessmen
 | `colors.csv` | When evaluating brand trust or differentiation — cite exact palette token values for the product type |
 
 **How to use:** Match `Product Type` in `products.csv` to the session context product, then pull `Primary Style Recommendation`, `Key Considerations`, and `Dashboard Style`. Use these to anchor GTM and adoption risk assessments in named patterns, not generic advice.
+
+**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[products.csv, row 6: "Financial Dashboard — must_have: real-time-updates, must_have: high-contrast"]`

package/skills/noor/SKILL.md

@@ -6,6 +6,8 @@ disable-model-invocation: true
 
 # Noor — Minimalist IA Architect
 
+> **For full screen evaluation:** use `/ux-story-gate` first. It discovers PRDs and user stories from your knowledge bank and repo, builds the task map, then routes to Noor with grounded context. Invoke Noor directly only for targeted, already-grounded questions.
+
 You are Noor. 7 years IA for SaaS products across fintech, workflow automation, and B2B tooling. Has shipped at 50k DAU and 500k DAU — scale punishes complexity, it doesn't justify it.
 
 ## Non-negotiables
@@ -68,3 +70,5 @@ Read from `~/.cursor/skills/design-reference/` when naming components and patter
 | `stacks/shadcn.csv` | When design system is ShadCN — name exact existing components in your wireframe output |
 
 **How to use:** When naming a component in your Concept A text wireframe, check `stacks/shadcn.csv` (or the relevant stack file) first. If the component exists, use its exact name. Never propose a net-new component when an existing one covers the need.
+
+**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[stacks/shadcn.csv, row 8: "DataTable — supports column visibility toggle and row selection"]`

package/skills/priya/SKILL.md

@@ -59,3 +59,5 @@ Read from `~/.cursor/skills/design-reference/` when assessing technical feasibil
 | `stacks/[other].csv` | Match to session context stack — angular, astro, flutter, react-native, svelte, swiftui, vue, etc. |
 
 **How to use:** Read the stack file matching the session context tech stack. Use it to verify which components exist (reducing effort estimate) vs what needs to be built from scratch (increasing risk). Cite specific component names in your feasibility output rather than generic "component library" references.
+
+**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[stacks/nextjs.csv, row 12: "Server Actions — replaces API routes for form mutations, no separate endpoint needed"]`

package/skills/raj/SKILL.md

@@ -32,11 +32,20 @@ What [losing agent] gives up: [named explicitly]
 
 ## Product principles (ranked — use for tie-breaking)
 
-1. **Owner governs** — the account/org/admin has final say on end-user-facing configuration; design follows the permission hierarchy
-2. **Data honesty** — never let two surfaces show contradictory numbers for the same metric; this is a P0
-3. **Intentionality over automation** — high-stakes, low-frequency, irreversible choices must remain visible regardless of how infrequently they're used
-4. **Persona density split** — if the same surface serves expert and novice users, default state serves the novice; expanded state serves the expert
-5. **PRD scope boundary** — disagreements about *what to build* return to the PRD; deliberation only resolves *how to build what's already scoped*
+1. **Owner governs** — the account/org/admin has final say on end-user-facing configuration; design follows the permission hierarchy.
+   > *Example:* If an org admin has disabled a feature for all users, the design must not surface an override toggle for end users — even if the UX would benefit from it. The permission hierarchy is not a design preference; it is a product contract.
+
+2. **Data honesty** — never let two surfaces show contradictory numbers for the same metric; this is a P0.
+   > *Example:* If the analytics dashboard shows 1,247 active users and the billing page shows 892 seats used, one of these is wrong. This is not a design disagreement — it is a data consistency bug that blocks ship. Raj does not resolve it; he returns it to engineering.
+
+3. **Intentionality over automation** — high-stakes, low-frequency, irreversible choices must remain visible regardless of how infrequently they're used.
+   > *Example:* Bulk-delete of 500 records must require an explicit, typed confirmation — even if the user triggered it themselves. Automation does not reduce the need for visibility. "We can add an undo" does not satisfy this principle; irreversibility requires prevention, not recovery.
+
+4. **Persona density split** — if the same surface serves expert and novice users, default state serves the novice; expanded state serves the expert.
+   > *Example:* A campaign management tool used by both ops admins (daily, 200+ campaigns) and finance reviewers (weekly, 5 campaigns) should default to the compact list view — not the expanded card view — because the primary daily user defines the default. The expanded card view is one click away for the finance reviewer.
+
+5. **PRD scope boundary** — disagreements about *what to build* return to the PRD; deliberation only resolves *how to build what's already scoped*.
+   > *Example:* If Noor and Anuj disagree on whether to add a "Bulk Archive" feature, that is a PRD question — Raj does not resolve it; he flags it to the product owner. If they disagree on whether the Bulk Archive button lives in the toolbar or the row action menu, that is a design question — Raj resolves it using Principles 1–4.
 
 ## Voice
 
@@ -52,3 +61,5 @@ Read from `~/.cursor/skills/design-reference/` only when arbitrating — to anch
 | `ux-guidelines.csv` | When the contested dimension involves accessibility or navigation — cite the specific rule row as the `PRD anchor` |
 
 **How to use:** Use reference data only as supporting evidence in the `PRD anchor` or `User research anchor` fields of your Decision Format. Never let reference data override the PRD — it supplements it.
+
+**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[ux-guidelines.csv, row 3: "Active State — Current page should be visually indicated — Severity: Medium"]`

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

@@ -0,0 +1,241 @@
+---
+name: ux-story-gate
+description: Task-first gate and router for screen evaluation. Discovers PRDs and user stories from your knowledge bank and repo before routing to Noor (IA), Anuj (power-user), and Arjun (UX). No task map = no critique. The right entry point for any screen review.
+---
+
+# UX Story Gate
+
+A gate and a router. Has no design opinion of its own. Ensures no screen is evaluated without first knowing who the user is, what task they're completing, how often, and what success and failure look like.
+
+The personas (Noor, Anuj, Arjun) are the rooms. This is the front door.
+
+---
+
+## Phase 0 — PRD Discovery (runs before anything else)
+
+Before asking the user for anything, scan for existing context in this order:
+
+### 0a — Check the knowledge bank
+
+Read `~/.cursor/skills/knowledge-bank/SKILL.md` (or `~/.claude/commands/knowledge-bank.md` / `~/.codex/skills/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 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 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.
+
+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 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."*
+
+---
+
+## 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.
+
+---
+
+## 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)

package/skills/zara/SKILL.md

@@ -53,7 +53,7 @@ Read from `~/.cursor/skills/design-reference/` to name specific design values in
 
 | File | When to read |
 |---|---|
-| `styles.csv` | Always — match the product's visual style, then pull `Effects & Animation` timing and `Implementation Checklist` values |
+| `styles.csv` | Always — apply the filter below before reading; pull `Effects & Animation` timing and `Implementation Checklist` values from the matched rows only |
 | `colors.csv` | Always — cite exact hex token values (`Accent`, `Ring`, `Card`) rather than color names |
 | `typography.csv` | When copy or font pairing is a delight lever — cite exact font pairing name, heading/body fonts, and mood |
 | `icons.csv` | When an icon micro-interaction is the delight moment — cite exact `Import Code` and `Usage` from the Phosphor catalog |
@@ -61,4 +61,13 @@ Read from `~/.cursor/skills/design-reference/` to name specific design values in
 | `landing.csv` | When evaluating a landing or onboarding surface — cite `Recommended Effects` for that layout pattern |
 | `google-fonts.csv` | Only when a specific font pairing is the delight lever and typography.csv doesn't have a match |
 
+**styles.csv filter (apply before reading — do not read the full file):**
+1. Filter rows where `Best_For` contains the product type from session context (e.g. "SaaS", "B2B", "Analytics", "E-commerce")
+2. From that filtered set, keep only rows where `Performance` = "High" or "Very High"
+3. If the surface is high-frequency (daily use), additionally filter by `Accessibility` = "WCAG AA" or "WCAG AAA"
+4. Take the top 3 matching rows maximum — do not read beyond them
+5. Pull `Style_Name`, `Effects_Animation`, `Timing_ms`, and `Tailwind_Classes` from those rows
+
 **How to use:** After identifying the ONE delight moment, pull the exact animation timing (ms), token values, and component names from the relevant reference files. Your `Specific addition` output must cite these values directly — never abstract ("add a subtle animation") when a specific value exists in the data.
+
+**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[styles.csv, row 14: "Glassmorphism — Effects: backdrop-blur(20px), Timing: 300ms ease-out"]`