wize-dev-kit 0.1.4 → 0.2.0

package/src/method-skills/1-analysis/wize-research/workflow.md

@@ -3,22 +3,114 @@ code: wize-research
 name: Research
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
-status: stub
+status: ready
 ---
 
 # Research
 
-**Goal.** Synthesize external evidence (market, competitors, analytics, interviews) that informs the brief.
+**Goal.** Surface evidence that hardens the brief and trigger map. Frame the questions Pepper actually needs answered, do focused passes (market / competitors / analytics / interviews), and write the synthesis in a way Maria Hill can quote in the PRD.
+
+Pepper drives. Peggy edits prose. Output lands in `.wize/planning/research.md` with raw materials in `.wize/knowledge/research/`.
 
 ## Inputs
-- Research questions from the brief
-- External access (browser, MCPs) and/or attached docs
+
+- Open questions in `.wize/planning/brief.md`.
+- Hypotheses in `.wize/planning/ux/trigger-map.md`.
+- External access (browser, MCPs) and/or attached materials (decks, transcripts).
 
 ## Outputs
-- `.wize/planning/research.md`
+
+- `.wize/planning/research.md` — short synthesis (≤ 2 pages) referencing sources.
+- `.wize/knowledge/research/{slug}.md` — one file per major source (raw notes, links, attached PDFs).
 
 ## Steps
-1. List the questions to answer.
-2. For each question: gather sources, summarize, cite.
-3. Mark gaps explicitly as `open` so Wizer can re-route.
-4. Hand off back to brief workflow.
+
+### 1. Frame the questions
+
+Convert open questions + hypotheses into a numbered list. Each question is:
+- **Specific** — "What's the median onboarding time for the top 5 competitors?" not "How is onboarding usually done?".
+- **Answerable in a finite pass** — if it takes weeks, decompose.
+- **Tagged with category** — `market / competitive / analytics / interview / desk-research / regulatory`.
+
+### 2. Choose the framework that fits each question
+
+| Category | Recommended frame | Tools |
+|---|---|---|
+| Market sizing | TAM/SAM/SOM, top-down + bottom-up reconciled | Statista, public filings, gov registries |
+| Competitive | Porter's 5 + feature matrix + pricing scan | competitor sites, G2/Capterra, Pricing/Plans pages |
+| User research | Jobs-to-be-Done (Christensen / Klement) | 5–8 interviews (semi-structured, 30min) |
+| Behavioral | 5W2H + analytics funnel | product analytics (Amplitude/PostHog), session replays |
+| Compliance/legal | Reg list + clause map | gov sites, legal counsel review |
+| Macro context | PESTLE (political/economic/social/technological/legal/environmental) | desk research |
+
+### 3. Run focused passes
+
+One question, one pass. Don't bundle. For each:
+
+- Define what "enough evidence" looks like before starting.
+- Cite or it didn't happen. Links + access date.
+- When numbers conflict across sources, write down both and flag.
+
+### 4. Synthesize
+
+In `research.md`, for each original question, write:
+
+```markdown
+### Q1. {{the question}}
+**Finding:** one sentence answer.
+**Confidence:** high | medium | low
+**Why we believe it:** 2–3 lines + citations [1][2][3].
+**Implication for the brief/PRD:** what changes (or doesn't) because of this.
+```
+
+Don't include raw quotes here — link to `.wize/knowledge/research/{slug}.md`.
+
+### 5. Flag the gaps
+
+End the synthesis with a "Still open" section. List questions we couldn't answer + the cheapest next step (one interview / one analytics query / one expert call). Route back to Wizer with the gap.
+
+## Output template (synthesis)
+
+```markdown
+---
+status: ready-for-prd
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# Research — {{project_name}}
+
+## Q1. {{question}}
+**Finding:** …
+**Confidence:** medium
+**Why:** … [1]
+**Implication:** Brief constraint #3 holds; PRD scope can drop feature X.
+
+## Q2. …
+
+## Still open
+- Q5: pricing elasticity in segment S — needs 1 hour with sales lead.
+
+## Sources
+[1] {{title}} — {{url}} (accessed YYYY-MM-DD)
+[2] interview-acme-cto-2026-05-30 — see knowledge/research/acme-cto.md
+```
+
+## When to use which framework (heuristic)
+
+- **JTBD** when you're about to write personas; JTBD is sharper than archetypes.
+- **Porter** when picking a market to enter or a defensible moat.
+- **PESTLE** for projects with regulatory or geopolitical exposure.
+- **5 Whys + analytics funnel** when a metric is bad and the cause isn't obvious.
+
+## Anti-patterns Pepper rejects
+
+- Synthesis without citations.
+- "We surveyed users" with no n, no method, no script.
+- Single-source claims with high confidence ("everyone is using X" because of one blog post).
+- Using brand-name competitor research as user research — they're different.
+- Continuing to research when the decision is already made. Stop and ship.
+
+## Hand-off
+
+> Research is in `.wize/planning/research.md`. Q3 still open — sales lead has a slot tomorrow. Hill can start the PRD on what's confirmed.

package/src/method-skills/1-analysis/wize-trigger-map/workflow.md

@@ -4,17 +4,21 @@ name: Trigger Map
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
 absorbs: "WDS Saga — Phase 2 (Trigger Mapping)"
-status: stub
+status: ready
 ---
 
 # Trigger Map
 
-**Goal.** Map user psychology to business goals. For each user action we want to drive, identify the **trigger** (need/anxiety/desire) and the **business outcome** it unlocks.
+**Goal.** Map user psychology to business goals. For each user action the product wants to drive, name the **trigger** (the need/anxiety/desire that precedes it), the **friction** that blocks it today, the **business outcome** unlocked, and the **signal** that confirms it happened.
+
+This is the bridge between Pepper's brief and Maria Hill's PRD: it forces the team to argue *why* users would do the thing before *what* the team will build.
+
+Pepper drives. Output lands in `.wize/planning/ux/trigger-map.md`.
 
 ## Inputs
 
-- `.wize/planning/brief.md`
-- `.wize/planning/research.md` (if exists)
+- `.wize/planning/brief.md` (vision + audience + success criteria).
+- `.wize/planning/research.md` (when present — strengthens triggers with evidence).
 
 ## Outputs
 
@@ -22,19 +26,79 @@ status: stub
 
 ## Steps
 
-1. **List target user actions.** From the brief, list the 3–8 actions we want users to take.
-2. **For each action**, fill the row:
-   - **Trigger** — what state of mind/need precedes this action?
-   - **Friction** — what stops users from doing it today?
-   - **Business outcome** — what changes for the business when this action happens?
-   - **Signal** — what telemetry/event proves it happened?
-3. **Validate.** Cite research or mark `hypothesis`.
-4. **Hand off to Mantis** for UX Scenarios.
+### 1. List target user actions
+
+From the brief, list **3–8 actions** users must take for the product to succeed. Verb-led. Concrete.
+
+- ✓ "Sign up using a work email."
+- ✓ "Add a teammate."
+- ✓ "Confirm the first invoice."
+- ✗ "Get value." (too abstract)
+
+If you have more than 8, you're conflating products. Trim.
+
+### 2. Per row: trigger / friction / business outcome / signal
+
+For each action, fill four cells. Each cell ≤ 1 sentence.
+
+| Field | What goes here |
+|---|---|
+| **Trigger** | The mental state preceding the action. *Need / anxiety / desire.* What makes the user think "I need to do this now"? |
+| **Friction** | The cost of doing it today (in the current workaround or competitor). What stops them? |
+| **Business outcome** | What changes for the business when this action happens. Revenue, retention, cost, NPS, risk reduction. |
+| **Signal** | The telemetry event/state-change proving it happened. Name it like an event (`signup_succeeded`), not a phrase ("user signs up"). |
+
+### 3. Mark each row evidence-backed or hypothesis
+
+Every cell must be tagged:
+
+- `evidence:<source>` — when based on an interview, survey, analytics or a citable doc.
+- `hypothesis` — when we believe it but haven't proven it.
+
+Hypotheses are fine. Hidden hypotheses are not. Force the label.
+
+### 4. Wire to success criteria
+
+For each of Pepper's success criteria in the brief, identify **which row of the map is the load-bearing one**. If a criterion has no row mapped to it, either it's not a real success criterion or the map is missing an action.
 
-## Trigger Map template
+### 5. Hand off
+
+Mark `status: ready-for-prd`. Tell Wizer the next step is Maria Hill.
+
+## Output template
 
 ```markdown
-| Action | Trigger | Friction | Business outcome | Signal | Evidence |
-|---|---|---|---|---|---|
-| … | … | … | … | … | research:/hypothesis |
+---
+status: ready-for-prd | draft
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# Trigger Map — {{project_name}}
+
+## Actions
+
+| # | Action | Trigger | Friction | Business outcome | Signal | Evidence |
+|---|---|---|---|---|---|---|
+| 1 | Sign up with work email | "We need a tool we can hand to the team next week." | Existing tool requires manual SSO; we want self-serve. | New paid-team conversion. | `signup_completed` | research:user-interview-2026-04 |
+| 2 | Invite first teammate | Won't move forward solo. | Email + reminder loops cost manager 10min. | Activation. | `teammate_invited` | hypothesis |
+| … | … | … | … | … | … | … |
+
+## Coverage of brief success criteria
+
+- **Criterion 1** ("TTI ≤ 1.5s on Android by Q3") → covered by row 4 (`page_loaded`).
+- **Criterion 2** ("…") → covered by row 1.
+- …
 ```
+
+## Anti-patterns Pepper rejects
+
+- **Triggers written as features.** "Wants the dashboard." Wrong layer. Reword to the emotion/need: "Wants to know if the team is okay."
+- **Friction in vague language.** "It's confusing." Wrong. Name the step that breaks: "After invite, no email arrives for 4 hours."
+- **Business outcomes with no metric.** "Drives engagement." Wrong. "Reduces churn by ≥ 1pp in cohort C." If you can't measure it, it's not an outcome — it's a hope.
+- **Signals that fire on intent, not completion.** `signup_button_clicked` is intent. `signup_completed` is the signal.
+- **Same row repeated for two actions.** Each row must justify a distinct action. If you can collapse them, do it.
+
+## Hand-off
+
+> Trigger map is in `.wize/planning/ux/trigger-map.md`. Hill, the PRD goals should anchor on rows 1, 3, and 5 — they map to the success criteria in the brief.

package/src/method-skills/2-plan-workflows/wize-create-prd/workflow.md

@@ -3,55 +3,164 @@ code: wize-create-prd
 name: Create PRD
 phase: 2-plan
 owner: wize-agent-pm   # Maria Hill
-status: stub
+status: ready
 ---
 
 # Create PRD
 
-**Goal.** Turn brief + research + trigger-map into a Product Requirements Document the team can build from.
+**Goal.** Turn brief + research + trigger map into a Product Requirements Document the team can build from. The PRD names *what* and *why* with measurable boundaries. Mantis, Fury, Tony will read it. Shuri ships against the acceptance criteria.
+
+Maria Hill drives. Peggy edits prose. Output lands in `.wize/planning/prd.md`.
 
 ## Inputs
-- `.wize/planning/brief.md`
-- `.wize/planning/research.md`
-- `.wize/planning/ux/trigger-map.md`
+
+- `.wize/planning/brief.md` (vision, audience, success criteria).
+- `.wize/planning/research.md` (when present).
+- `.wize/planning/ux/trigger-map.md` (every PRD goal references rows of this map).
+- `.wize/planning/prfaq.md` (when present — PRD scope mirrors FAQ Q5 "what's in/out").
 
 ## Outputs
+
 - `.wize/planning/prd.md`
+- `.wize/solutioning/epics/` — coarse epic outlines Tony refines later.
 
 ## Steps
-1. **Goals.** Pull the success criteria from the brief; restate as PRD goals.
-2. **Scope (in / out).** Explicit list of in-scope and out-of-scope items.
-3. **User stories backbone.** "As a … I want … so that …" — coarse, will be sliced by Tony.
-4. **Acceptance criteria per scope item.** Each scope item gets ACs Hawkeye can test.
-5. **Constraints + assumptions.** From brief and Fury (if Fury has run already).
-6. **Open questions.** Owners assigned.
-7. **Hand-off.** Trigger Mantis to start UX scenarios.
 
-## PRD template
+### 1. Goals (3–5)
+
+Pull the success criteria from the brief; restate as PRD goals. Each goal is:
+- One sentence.
+- Measurable (named metric + target + deadline).
+- Tied to a trigger-map row.
+
+Example: *"Reduce signup time from 3.5min to 1min by Q3 (signal: `signup_completed` median; row 1)."*
+
+### 2. Scope — in / out (explicit)
+
+| In | Out (for now) |
+|---|---|
+| First-team signup flow | Multi-team admin roles |
+| Self-serve invite | SSO via SAML |
+| English (US) | Other locales |
+
+If a stakeholder asked for it and it isn't here, they will ask again at gate review. Put their item in **Out** with a one-line reason, not silence.
+
+### 3. User stories backbone
+
+Coarse stories that map to scope items. "As a {role}, I want to {action}, so that {outcome}." Each story will be sliced finer by Tony in `wize-create-epics-and-stories`.
+
+Use the trigger-map rows as backbone:
+- Row 1 (Sign up) → "As a team admin, I want to sign up with my work email, so that I can invite my team within 5 minutes."
+
+### 4. Acceptance criteria per scope item
+
+For every In-scope item, write 3–7 ACs Hawkeye can test.
+
+Format: `Given … When … Then …` or a numbered behavioral list.
+
+ACs are **observable**. ✓ "If the user enters an invalid email, the input shows error text within 200ms." ✗ "The form validates emails correctly."
+
+Each AC gets an ID: `AC-{epic}-{n}`. Hawkeye references these in `tea-trace.md`.
+
+### 5. Constraints + assumptions
+
+Pull constraints from the brief. Add:
+- **Assumptions** that, if wrong, change scope.
+- **Dependencies** on other teams/services with name + deadline.
+
+Each assumption is one line + verification plan. *"Assumption: Stripe Connect onboarding average 7 days. Verification: confirm with Stripe by 2026-07-01."*
+
+### 6. NFR pointer
+
+Don't redefine NFRs in the PRD. Reference `.wize/planning/nfr-principles.md` (Fury's) once. Note any project-specific tightening.
+
+### 7. Open questions
+
+What still needs deciding before solutioning starts. Each with an owner + deadline. Blockers can't carry into Phase 3.
+
+### 8. Hand off
+
+- Mark `status: ready-for-validation`.
+- Run `wize-validate-prd` (Maria Hill + Mantis + Fury sign-off).
+- Then Mantis starts `wize-ux-scenarios`.
+
+## Output template
 
 ```markdown
+---
+status: draft | ready-for-validation | validated
+owner: Maria Hill
+created: YYYY-MM-DD
+---
+
 # PRD — {{project_name}}
 
 ## Goals
-1. …
+1. {{goal}} (metric: …, target: …, deadline: …, trigger-map row: …)
+2. …
 
 ## Scope
+
 ### In scope
-- …
+- {{item}} — {{2–3 lines of detail}}
+
 ### Out of scope
-- …
+- {{item}} — {{one-line reason: not now / not us / not yet}}
 
-## Backbone (user stories)
-- …
+## Backbone (coarse stories)
+- E01: As a {{role}}, I want to {{action}}, so that {{outcome}}.
+- E02: …
 
 ## Acceptance criteria
-| Item | ACs |
-|---|---|
-| … | AC1 …; AC2 … |
 
-## Constraints / assumptions
+### E01 — Sign-up
+- **AC-01-1:** Given a new visitor on `/signup`, When they submit a valid work email + password, Then an account is created and they land on `/onboarding` within 1.5s.
+- **AC-01-2:** Given an invalid email, When the user blurs the field, Then error text appears within 200ms identifying which rule failed.
+- **AC-01-3:** Given a duplicate email, When the user submits, Then they see a "Sign in instead?" CTA and the request returns HTTP 409.
 - …
 
+## Constraints
+- Deadline: …
+- Budget: …
+- Compliance: GDPR, LGPD, SOC2.
+
+## Assumptions
+- Stripe Connect onboarding ≤ 7 days avg. — verify by …
+- Auth0 free tier sufficient for first 6 months. — verify by …
+
+## Dependencies
+- Design system tokens from Mantis by {{date}}.
+- Database from infra team by {{date}}.
+
+## NFR pointer
+See `.wize/planning/nfr-principles.md`. Project tightening: p95 LCP ≤ 2.0s (vs. global 2.5s) on signup pages.
+
 ## Open questions
-- [ ] … (owner: …)
+- [ ] (blocker) Pricing tier exposed pre-payment? — *owner: NAME, by: DATE*
+- [ ] (important) Brazil-only beta or global launch? — *owner: NAME, by: DATE*
 ```
+
+## INVEST checklist (per AC group)
+
+Maria Hill validates every story's ACs against INVEST:
+
+- **I**ndependent: no implicit dependency on another story being built first.
+- **N**egotiable: details can move; intent can't.
+- **V**aluable: a real outcome to a real user.
+- **E**stimable: Tony can size it.
+- **S**mall: ≤ 1 PR worth (sliced finer in Phase 3 if not).
+- **T**estable: every AC is observable.
+
+If any letter fails, fix the story before it leaves Plan.
+
+## Anti-patterns Maria Hill rejects
+
+- **PRD as wishlist.** Pages of "the system shall…" with no Out-of-Scope. Force the cut.
+- **ACs as descriptions.** "The form is responsive." → no. *"At 360px, the form fits in the viewport with no horizontal scroll."*
+- **Open questions with no owner / no deadline.** They never get answered.
+- **Constraint hidden in prose.** Pull to its own bullet.
+- **PRD without a version + status.** Reviewers can't tell what they're reviewing.
+
+## Hand-off
+
+> PRD draft is at `.wize/planning/prd.md`. Two open blockers; CEO and Sales Lead have until Friday. Mantis — once we're `validated`, you start with the trigger map + PRD. Fury — your call on stack family.

package/src/method-skills/2-plan-workflows/wize-ux-design/workflow.md

@@ -4,63 +4,167 @@ name: UX Design
 phase: 2-plan
 owner: wize-agent-ux-designer   # Mantis
 absorbs: "WDS Freya — Phase 4 (Page Specs)"
-status: stub
+status: ready
 ---
 
 # UX Design
 
-**Goal.** Page-by-page specifications. Each screen documents layout, content, interactions, edge/empty/error states.
+**Goal.** Turn scenarios into page-by-page specifications Tony can architect against and Shuri can implement. One spec per screen. Every spec answers: purpose, primary action, layout, content, interactions, states (loading/empty/error/success/disabled), accessibility, and metrics.
+
+Mantis drives. Output lands in `.wize/planning/ux/ux-design/{screen-name}.md`.
 
 ## Inputs
-- `.wize/planning/ux/ux-scenarios.md`
-- `.wize/planning/prd.md`
+
+- `.wize/planning/ux/ux-scenarios.md` (every screen traces back to ≥ 1 scenario)
+- `.wize/planning/prd.md` (every screen advances at least one AC)
+- `.wize/solutioning/design-system/` (when Mantis already wrote tokens; otherwise this runs in parallel with `wize-design-system`)
+- Overlay playbooks if active:
+  - `web-overlay/playbooks/wcag-aa.md`, `responsive-breakpoints.md`, `semantic-html.md`
+  - `app-overlay/playbooks/apple-hig.md`, `material-design-3.md`, `touch-targets-and-gestures.md`, `permissions-ux.md`
 
 ## Outputs
+
 - `.wize/planning/ux/ux-design/{screen-name}.md` (one per screen)
+- `.wize/planning/ux/ux-design/index.md` (map of screens → scenarios → PRD ACs)
+
+## Steps
+
+### 1. Enumerate the screens
+
+From the scenarios, list every screen needed to deliver the moment-of-truth. Name them by role + state: `signup-empty.md`, `signup-error.md`, `team-list-with-members.md`, `team-list-empty.md`. Empty/error/loading states are screens.
+
+### 2. Per screen: fill the spec template
+
+For each screen, write the spec below. Stay disciplined; if a section is empty, ask why.
 
-## Per-screen template
+### 3. Write the index
+
+`index.md` is a single table mapping screen → scenarios touched → PRD ACs advanced. Tony reads this first; Hawkeye references it in `tea-design.md`.
+
+### 4. Hand off
+
+Mark `status: ready-for-architecture` on each spec. Notify Wizer; Tony reads next.
+
+## Spec template (one file per screen)
 
 ```markdown
 ---
-screen: {{name}}
-linked_scenario: ux-scenarios.md#scenario-N
+screen: signup-empty
+status: ready-for-architecture
+owner: Mantis
+linked_scenarios: [S1]
+linked_acs: [AC-01-1, AC-01-2]
 ---
 
-# {{Screen name}}
+# Sign up (empty state)
 
 ## Purpose
-…
+First contact: a manager wants to create an account. The goal of *this* screen is to collect work email + password with minimum friction, in service of scenario S1 moment-of-truth (3 invites within 5 minutes).
 
 ## Primary user action
-…
+Submit the form (CTA: "Create account").
 
-## Layout (ASCII wireframe or description)
+## Layout (ASCII or Mermaid)
+
+(web overlay)
 ```
-┌───────────────────────────────────────┐
-│ Header                                │
-├───────────────────────────────────────┤
-│ Content                               │
-└───────────────────────────────────────┘
+┌─────────────────────────────────────────────────┐
+│ Wize logo                          [Sign in →]  │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│           Create your team's account            │
+│           ──────────────────────────            │
+│           [ Work email           ]              │
+│           [ Password (12+)       ]              │
+│                                                 │
+│           [    Create account    ]              │
+│                                                 │
+│           Already a member? Sign in              │
+│                                                 │
+└─────────────────────────────────────────────────┘
 ```
 
-## Content
-- Headline: …
-- Body: …
-- CTA: …
+(app overlay note: stacked, top-aligned, system back disabled.)
+
+## Content (copy)
+
+- Headline: "Create your team's account"
+- Sub: (none — keep the screen empty for focus)
+- Field 1 label: "Work email"
+- Field 1 placeholder: "name@yourcompany.com"
+- Field 2 label: "Password"
+- Field 2 helper text: "At least 12 characters."
+- CTA: "Create account"
+- Secondary: "Already a member? Sign in" → routes to /signin
 
 ## Interactions
-- Click {{element}} → {{outcome}}
+
+- Click CTA with valid form → submit; show loading state; redirect on success.
+- Click CTA with invalid form → set focus to first invalid field; show error region.
+- Tab order: email → password → CTA → "Sign in" link.
+- Enter on either field submits if both are valid.
 
 ## States
-- Loading: …
-- Empty: …
-- Error: …
-- Success: …
+
+- **Loading:** CTA shows spinner; button is disabled; inputs remain editable.
+- **Empty (this state):** placeholders visible; CTA disabled until both fields non-empty.
+- **Error (inline per field):** error region appears under each field, `role="alert"`, identifies the rule and the fix.
+- **Error (global):** Banner above headline if the back-end fails with a non-field error; provides a "retry" action.
+- **Success:** redirect; no flash. The next screen owns acknowledgement.
+- **Disabled:** CTA opacity 0.4; aria-disabled="true"; tooltip *"Fill both fields to continue"*.
 
 ## Accessibility notes
-- (web-overlay) WCAG …
-- (app-overlay) HIG / Material …
+
+(web overlay)
+- Both inputs have visible persistent labels (no placeholder-only).
+- `lang="en"` on `<html>`.
+- Error region: per-field `aria-describedby`, ALL `role="alert"` after first submit only.
+- Contrast pairs all ≥ 4.5:1 in light mode, ≥ 4.5:1 in dark mode.
+- 200% zoom: no horizontal scroll on 360px viewport.
+- Skip link absent (no main nav before).
+
+(app overlay)
+- Apple HIG / Material 3 systemic input components.
+- Dynamic Type / font scale: layout reflows at largest accessibility size; CTA pinned to bottom-safe-area.
+- Touch targets ≥ 44pt (iOS) / 48dp (Android).
+- VoiceOver order: headline → email → password → CTA → secondary link.
+
+## Metrics
+
+- Event `signup_completed` (Q7 success quote): fires after redirect.
+- Event `signup_error_shown {rule}`: fires on inline error.
+- Event `signup_abandoned`: fires on `beforeunload` if form had focus and CTA never fired.
+
+## Open questions for Tony
+
+- Should we use Auth0 hosted UI or our own form? (UX-decision is to keep our own; Tony decides feasibility.)
+- Magic-link as an alternative path? Out of scope per PRD; Mantis recommends putting in *Out*.
 ```
 
+## Index template
+
+```markdown
+# UX Design — index
+
+| Screen | Scenarios | PRD ACs |
+|---|---|---|
+| signup-empty | S1 | AC-01-1, AC-01-2 |
+| signup-error | S1 | AC-01-2 |
+| onboarding-step-1 | S1 | AC-02-1 |
+| team-list-empty | S1, S2 | AC-03-1 |
+| team-list-with-members | S1, S2 | AC-03-2, AC-03-3 |
+| invite-modal | S1, S2 | AC-02-2, AC-02-3 |
+```
+
+## Anti-patterns Mantis rejects
+
+- **Specs without states.** A screen with no empty/error spec is half a spec.
+- **Copy as marketing tone.** Use the user's voice. Cut "world-class," "delightful," "seamless."
+- **Mystery icons.** Icons need accessible labels; if you can't name it, draw a word next to it.
+- **Hover-only affordances on touch.** Spec the non-hover equivalent.
+- **Touch targets < platform minimum.** 24×24 CSS px on web (WCAG 2.5.8), 44pt iOS, 48dp Android — non-negotiable.
+- **Screens that don't trace to scenarios + PRD ACs.** If you can't fill the index row, the screen isn't justified.
+
 ## Hand-off
-"Tony, screen specs in `.wize/planning/ux/ux-design/`. Architecture time."
+
+> UX specs are at `.wize/planning/ux/ux-design/`. Index points screen → scenario → AC. Tony, you can start `wize-create-architecture` now; the moment-of-truth lines in scenarios tell you which interactions are load-bearing. Hawkeye, `tea-design.md` should index by screen to keep test design and UI aligned.