analyzthis_design 1.4.0 → 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

@@ -70,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/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"]`