wize-dev-kit 0.1.5 → 0.2.5

package/src/method-skills/3-solutioning/wize-design-system/workflow.md

@@ -4,33 +4,193 @@ name: Design System
 phase: 3-solutioning
 owner: wize-agent-ux-designer   # Mantis (WDS Freya — Phase 7)
 absorbs: "WDS Freya — Phase 7 (Design System)"
-status: stub
+status: ready
 ---
 
 # Design System
 
-**Goal.** Establish design tokens and a baseline component library that Shuri implements consistently across the product.
+**Goal.** Establish design tokens and a baseline component library Shuri implements consistently. Mantis defines what; Tony picks the runtime; Shuri builds. Hawkeye verifies a11y and consistency at gate.
+
+Mantis drives. Output lands in `.wize/solutioning/design-system/`.
 
 ## Inputs
-- `.wize/planning/ux/ux-design/`
+
+- `.wize/planning/ux/ux-design/` (every component the specs use)
+- `.wize/planning/nfr-principles.md` (a11y and perf budgets)
+- Overlay playbooks (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`
 
 ## Outputs
-- `.wize/solutioning/design-system/tokens.json`
-- `.wize/solutioning/design-system/components/{Component}.md`
-- `.wize/solutioning/design-system/README.md`
-
-## Tokens covered
-- color (semantic + raw scale)
-- typography (family, sizes, weights, line-heights)
-- spacing scale
-- radii
-- motion (durations, easings)
-- shadows / elevation
-- z-index layers
-
-## Component baseline
-Buttons, inputs, selects, modals, dialogs, tabs, cards, notifications. Enough for the first epic; expand as stories require.
-
-## Overlays
-- **Web overlay** active → responsive token variants, REM-based typography.
-- **App overlay** active → platform-token sets (iOS / Android), touch-friendly spacing scale.
+
+- `.wize/solutioning/design-system/tokens.json` — single source of truth.
+- `.wize/solutioning/design-system/components/{Component}.md` — one per component.
+- `.wize/solutioning/design-system/README.md` — index + theming guide.
+
+## Tokens (the only acceptable way to ship styles)
+
+Mantis defines the tokens; Tony picks the runtime (Tailwind, CSS modules, Vanilla Extract, Compose theme, SwiftUI tokens). The names below are framework-agnostic.
+
+### Color (semantic + raw scale)
+
+| Semantic | Light | Dark | Contrast pair |
+|---|---|---|---|
+| `surface.base` | #FFFFFF | #0B0F14 | text.primary |
+| `surface.raised` | #F5F7FA | #121821 | text.primary |
+| `text.primary` | #0B0F14 | #E5E7EB | surface.base |
+| `text.secondary` | #4B5563 | #9CA3AF | surface.base |
+| `accent.brand` | #6F49FF | #8B6FFF | text.onAccent |
+| `text.onAccent` | #FFFFFF | #FFFFFF | accent.brand |
+| `success` | #058E5C | #34D399 | text.onSuccess |
+| `warning` | #C9621E | #F59E0B | text.onWarning |
+| `error` | #B42318 | #FCA5A5 | text.onError |
+| `border.default` | #E5E7EB | #2A313A | — |
+| `border.focus` | accent.brand | accent.brand | — |
+
+Validate every pair against WCAG AA (≥ 4.5:1 normal, ≥ 3:1 large). Run before you commit.
+
+### Typography
+
+| Token | Family | Size | Weight | Line | Letter |
+|---|---|---|---|---|---|
+| `display.l` | Inter Display | clamp(2.5rem, 5vw, 3.5rem) | 700 | 1.05 | -0.02em |
+| `display.m` | Inter Display | clamp(2rem, 4vw, 2.5rem) | 700 | 1.1 | -0.01em |
+| `heading.l` | Inter | clamp(1.5rem, 3vw, 2rem) | 600 | 1.2 | -0.01em |
+| `heading.m` | Inter | 1.25rem | 600 | 1.3 | 0 |
+| `heading.s` | Inter | 1rem | 600 | 1.4 | 0 |
+| `body.l` | Inter | 1.125rem | 400 | 1.6 | 0 |
+| `body.m` | Inter | 1rem | 400 | 1.55 | 0 |
+| `body.s` | Inter | 0.875rem | 400 | 1.5 | 0 |
+| `caption` | Inter | 0.75rem | 500 | 1.4 | 0.01em |
+
+Use rem for body; clamp() for fluid headings (see `responsive-breakpoints.md`).
+
+### Spacing scale (4px base, geometric)
+
+`0` 0 · `1` 4 · `2` 8 · `3` 12 · `4` 16 · `5` 24 · `6` 32 · `7` 48 · `8` 64 · `9` 96 · `10` 128
+
+### Radius
+
+`none` 0 · `sm` 4 · `md` 8 · `lg` 12 · `xl` 16 · `pill` 999.
+
+### Elevation
+
+| Token | Light | Dark (tonal) |
+|---|---|---|
+| `e1` | 0 1px 2px rgba(0,0,0,.06) | surface.raised |
+| `e2` | 0 2px 4px rgba(0,0,0,.08) | surface.raised + 4% |
+| `e3` | 0 4px 12px rgba(0,0,0,.10) | surface.raised + 8% |
+| `e4` | 0 12px 24px rgba(0,0,0,.12) | surface.raised + 12% |
+
+App overlay: prefer tonal elevation per Material 3.
+
+### Motion
+
+| Token | Duration | Easing |
+|---|---|---|
+| `motion.micro` | 100ms | `ease-out` |
+| `motion.transition` | 200ms | `cubic-bezier(0.2, 0, 0, 1)` |
+| `motion.page` | 300ms | `cubic-bezier(0.4, 0, 0.2, 1)` |
+| `motion.spring.subtle` | (spring) | mass 1, stiff 350, damp 30 |
+
+Honor `prefers-reduced-motion`. Replace transforms with fades.
+
+## Components — the baseline set
+
+Each component has its own `.md` doc with: purpose, anatomy, states (default/hover/focus/active/disabled/loading), variants, accessibility, do/don't, snippets.
+
+| Component | Mandatory states | Notes |
+|---|---|---|
+| Button | default, hover, focus, active, disabled, loading | variants: primary, secondary, tertiary, destructive, ghost |
+| Input | default, focus, error, disabled, success | always has visible label |
+| Select | default, open, focus, disabled | native first; custom only when needed |
+| Textarea | as Input | auto-grow optional |
+| Checkbox | unchecked, checked, indeterminate, focus, disabled | native input + custom skin |
+| Radio | unchecked, checked, focus, disabled | grouped under fieldset |
+| Toggle/Switch | off, on, focus, disabled | `role="switch" aria-checked` |
+| Card | default, raised, interactive | elevation tokens |
+| Modal / Dialog | open, closing | focus trap + ESC + restore |
+| Sheet (app) | half / full | drag handle |
+| Tabs | active, inactive, focus | keyboard arrows |
+| Accordion | collapsed, expanded, focus | `<details>` when possible |
+| Toast / Snackbar | info, success, warning, error | `role="status"` or `alert` |
+| Tooltip | hidden, visible | `aria-describedby`, touch alt |
+| Menu | closed, open, focus | keyboard navigation |
+| Dropdown | (synonym of Menu / Combobox) | follow ARIA combobox |
+| Badge | default, success, warning, error | contrast ≥ 4.5:1 |
+| Avatar | image, initials, placeholder | 1:1 ratio, alt text |
+| Skeleton | static, shimmer | respect reduced-motion |
+| Empty state | default | message + primary action |
+| Loading | spinner / progress | accessible announcement |
+
+## Component template (one per component)
+
+```markdown
+---
+component: Button
+status: ready
+owner: Mantis
+linked_screens: [signup-empty, team-list-empty, …]
+---
+
+# Button
+
+## Purpose
+Trigger an action. Never use for navigation between routes.
+
+## Anatomy
+[icon?] [label] [icon?] · padding by size · radius `md`
+
+## Variants
+- `primary` — main action; one per screen region.
+- `secondary` — alternative action.
+- `tertiary` — text-only.
+- `destructive` — irreversible action.
+- `ghost` — minimal chrome, e.g., toolbar.
+
+## Sizes
+- `sm` (height 32, label `body.s`)
+- `md` (height 40, label `body.m`)
+- `lg` (height 48, label `body.m`)
+
+## States
+
+| State | Treatment |
+|---|---|
+| default | accent.brand bg, text.onAccent label |
+| hover | accent.brand 10% darker |
+| focus | 2px outline `border.focus`, offset 2px |
+| active | accent.brand 15% darker |
+| disabled | opacity 0.4, `aria-disabled="true"`, cursor not-allowed |
+| loading | spinner replaces icon; label unchanged; click ignored |
+
+## Accessibility
+- Native `<button>`.
+- `aria-label` when icon-only.
+- Visible focus ring always (don't override).
+- 24×24 px hit area minimum (web), 44pt (iOS), 48dp (Android).
+- Min contrast on label ≥ 4.5:1.
+
+## Don't
+- Use `<div onclick>`.
+- Remove the focus ring without replacement.
+- Use destructive for "Continue".
+- Stack > 2 primary buttons on a screen.
+```
+
+## Theming + overlays
+
+- **Web overlay:** tokens emit as CSS custom properties; dark mode toggled via `[data-theme="dark"]` on `<html>`.
+- **App overlay (iOS):** tokens as SwiftUI environment values; dark mode auto.
+- **App overlay (Android):** tokens as Compose `MaterialTheme` extensions; honor `dynamicColorScheme` when allowed.
+
+## Anti-patterns Mantis rejects
+
+- **Hex in components.** Everything via tokens.
+- **One-off components shipped without doc.** Add to the system or refuse to merge.
+- **Component matrix without states.** A button without disabled+loading isn't a button.
+- **Component that fails axe.** Failed at definition; don't ship.
+
+## Hand-off
+
+> Tokens + 20 components at `.wize/solutioning/design-system/`. Tony picks the runtime (Tailwind / Vanilla Extract / SwiftUI tokens / Compose theme); Shuri implements. Hawkeye references this in `tea-design.md`: a11y + visual regression hooks point at these tokens.

package/src/method-skills/3-solutioning/wize-nfr-principles/workflow.md

@@ -3,31 +3,157 @@ code: wize-nfr-principles
 name: NFR Principles
 phase: 2-to-3-boundary
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # NFR Principles
 
-**Goal.** Define non-functional non-negotiables Tony must design against and Hawkeye must verify.
+**Goal.** Define non-functional non-negotiables Tony must design against and Hawkeye must verify. Hill defers to this when sizing scope. Mantis respects the a11y/perf bars in UX specs. Shuri implements with these targets in hand.
+
+Fury drives. Output lands in `.wize/planning/nfr-principles.md`.
+
+## Inputs
+
+- `.wize/planning/prd.md`
+- `.wize/planning/tech-vision.md`
+- `.wize/planning/brief.md` (compliance constraints, audience implications)
+- Overlay perf playbooks if active:
+  - `web-overlay/playbooks/web-perf-budgets.md`
+  - `app-overlay/playbooks/mobile-perf-budgets.md`
+  - `web-overlay/playbooks/wcag-aa.md`
+  - `app-overlay/playbooks/apple-hig.md`, `material-design-3.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/nfr-principles.md`
 
-## Categories
-- **Performance** — targets (LCP, p95, throughput).
-- **Security** — auth model, data classes, threat surface posture.
-- **Reliability** — uptime, error budget, retry/idempotency policy.
-- **Maintainability** — coding standards, tech-debt allowance.
-- **Accessibility** — WCAG / platform guidelines minimums.
-- **Cost** — monthly envelope and degradation strategy.
+## Categories (always cover these six)
+
+For each, write **non-negotiable** + **stretch** + **deferred** (with trigger). Use the playbooks as starting points; **tighten** if PRD demands, never loosen below playbook recommendations.
+
+### 1. Performance
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | LCP ≤ 2.5s mobile, INP ≤ 200ms, CLS ≤ 0.1 (web) — cold start ≤ 1.5s mid-range (app) |
+| Stretch | LCP ≤ 1.8s, INP ≤ 100ms |
+| Deferred | Server-side LCP for edge regions — revisit when audience > 30% non-NA |
+
+### 2. Security
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | OWASP Top 10 covered; auth via {{vendor}}; tokens never logged; secrets via {{provider}}; RLS on every table with user_id |
+| Stretch | SOC2 type-I controls in place by {{date}} |
+| Deferred | SOC2 type-II — revisit at $1M ARR |
+
+### 3. Reliability
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | 99.9% uptime in primary region; error budget 0.1%/month; retries idempotent with deduplication key |
+| Stretch | 99.95% uptime |
+| Deferred | Multi-region active/active — revisit per tech-vision deferred |
+
+### 4. Maintainability
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | Lint + format on commit; > 80% test coverage on logic modules; ADRs for every architectural decision; deps audited monthly |
+| Stretch | < 5% files over 300 LOC; cyclomatic complexity < 15 per function |
+| Deferred | Auto-doc generation — revisit when API consumers > 3 |
+
+### 5. Accessibility
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | WCAG 2.2 AA on every shipped page; keyboard-complete; axe in CI |
+| Stretch | AAA on critical flows (signup, billing) |
+| Deferred | Full screen-reader manual audit every release — revisit at next compliance review |
+
+### 6. Cost
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | Total infra ≤ ${{X}}/month under {{load}}; degradation strategy documented for 10× spike |
+| Stretch | Cost-per-active-user ≤ ${{Y}} |
+| Deferred | Per-feature cost attribution — revisit when finance asks |
+
+## Steps
+
+### 1. Read the playbooks first
+
+If web/app overlays are active, the perf and a11y playbooks already hold real targets calibrated to mid-range device + 3G fast. Use them as starting point.
+
+### 2. Tighten by audience
+
+Mid-range mobile is the playbook baseline. If your PRD audience is *more* constrained (emerging markets, kiosk hardware, healthcare older devices), tighten. Don't loosen.
+
+### 3. Map every non-negotiable to a verifier
+
+Every non-negotiable must answer the question: *Who and how do we verify this on every release?*
+
+- LCP → `web-perf-budgets.md` lighthouse-ci config.
+- WCAG → axe in CI + Hawkeye review.
+- Uptime → SLO defined in `.wize/solutioning/observability.md` (Tony).
+- Error budget → tracked in {{tool}}.
+
+A non-negotiable with no verifier is a wish.
+
+### 4. Tell the story (one paragraph)
+
+Open the doc with a paragraph: *why these numbers, and what trade-offs they imply.* Future readers re-litigate non-negotiables every six months; the story saves that hour.
+
+### 5. Hand off
+
+Mark `status: aligned`. Tony reads before architecture; Hawkeye reads before risk profile.
+
+## Output template
 
-## Template
 ```markdown
-# NFR Principles
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
+
+# NFR Principles — {{project_name}}
+
+## Why these numbers
+
+{{One paragraph: target audience, country mix, device class, compliance frame. Why we picked these targets specifically.}}
+
+## Performance
+| Tier | Targets | Verifier |
+|---|---|---|
+| Non-negotiable | LCP ≤ 2.5s mobile (CWV), INP ≤ 200ms, CLS ≤ 0.1 | lighthouse-ci + web-vitals beacon |
+| Stretch | LCP ≤ 1.8s | same |
+| Deferred | Multi-region LCP — trigger: EU DAU > 5k | — |
 
-| Category | Non-negotiable | Stretch | Deferred |
-|---|---|---|---|
-| Performance | … | … | … |
-| Security | … | … | … |
+## Security
+…
+
+## Reliability
+…
+
+## Maintainability
+…
+
+## Accessibility
+…
+
+## Cost
 …
 ```
+
+## Anti-patterns Fury rejects
+
+- **Targets without numbers.** "Fast." Wrong. "p95 server response ≤ 200ms."
+- **Stretch targets that are actually goals.** If you must hit it, it's non-negotiable.
+- **No verifier.** Every non-negotiable answers *who verifies, with what tool, on what cadence*.
+- **Loosening below the playbook.** Tightening is fine. Loosening is a smell — escalate.
+- **Cost left blank.** Cost is always an NFR.
+
+## Hand-off
+
+> NFRs at `.wize/planning/nfr-principles.md`. Tony, architecture must respect items 1.A and 4.A from day one (perf and ADR discipline). Hawkeye, your gate policy can stay advisory but NFR gate per epic is mandatory. Hill, scope must keep the budget headroom for item 6.A.

package/src/method-skills/3-solutioning/wize-tech-vision/workflow.md

@@ -3,41 +3,147 @@ code: wize-tech-vision
 name: Tech Vision
 phase: 2-to-3-boundary
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # Tech Vision
 
-**Goal.** State the technical north star in one page. Stack family, language, runtime envelope, build/buy/borrow calls. Not libraries — *shape*.
+**Goal.** State the technical north star in one page. Stack family, runtime envelope, build/buy/borrow calls, non-negotiables. Fury sets the **shape**, not the libraries — Tony fills in inside the frame.
+
+Output lands in `.wize/planning/tech-vision.md`. Tony reads this before drawing architecture. Hill references it when scoping. Hawkeye uses it when picking gate granularity.
+
+## Inputs
+
+- `.wize/planning/prd.md` (validated)
+- `.wize/planning/ux/ux-design/` (so the runtime envelope respects the UX)
+- `.wize/knowledge/document-project/` (brownfield only)
+- Stack catalogs (per active overlay):
+  - `src/web-overlay/stack-catalog.md`
+  - `src/app-overlay/stack-catalog.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/tech-vision.md`
 
-## Template
+## Steps
+
+### 1. Pick the stack family
+
+By order of constraint:
+
+1. **Audience reach.** Public + SEO-critical? Authenticated app? Native mobile required?
+2. **Latency budget.** Sub-1s LCP on 3G or richer-but-slower OK?
+3. **Team familiarity.** Favor what the team has shipped before unless the project truly demands new.
+4. **Backend coupling.** Separate API / fullstack monolith / BaaS?
+5. **Deploy target.** Edge / container / self-managed.
+
+Don't pick libraries here. Pick the *shape*: "Next.js-class SSR fullstack on edge" or "React Native + Expo with a Supabase backend" or "Compose Multiplatform with Kotlin services."
+
+### 2. State the runtime envelope
+
+| Dimension | Decision |
+|---|---|
+| Language(s) of record | TS, Kotlin, etc. |
+| Runtime(s) | Browser / Node / Edge / Native iOS / Native Android / JVM |
+| Persistence | Postgres / SQLite / KV / cloud-native |
+| Deploy target | Vercel / Cloudflare / Fly / EKS / EAS / etc. |
+| Edge vs origin | Edge-first / origin-first |
+
+### 3. Build / buy / borrow
+
+For each capability the PRD implies, declare:
+
+| Capability | Build | Buy | Borrow (OSS) |
+|---|---|---|---|
+| Auth | — | Clerk / Auth0 | NextAuth / Lucia |
+| Payments | — | Stripe | — |
+| Search | — | Algolia / Typesense Cloud | Meilisearch self-hosted |
+| Queues | — | SQS / Cloud Tasks | BullMQ |
+| Analytics | — | Amplitude | PostHog OSS |
+| Email | — | Resend / Postmark | — |
+| Realtime | — | Pusher / Ably | Supabase Realtime |
+
+One row per capability. Empty cells are explicit choices.
+
+### 4. Non-negotiables
+
+The 2–5 things the team will not compromise on.
+
+Examples:
+- *"All endpoint responses ≤ 200ms p95 from the user's region."*
+- *"Single source of truth for user data — no shadow stores."*
+- *"PII never leaves the EU."*
+- *"On-call burden ≤ 0.5 pages per engineer per week."*
+
+These outrank PRD goals. If they conflict, Fury escalates.
+
+### 5. Deferred (with triggers)
+
+What we won't decide yet, and what would trigger the decision. Don't list "could be revisited"; list the *signal* that forces the decision.
+
+- *"Multi-region storage: revisit when EU+US daily active users > 5k."*
+- *"WebSockets vs SSE: revisit when realtime updates < 500ms become a PRD goal."*
+
+### 6. Hand off
+
+Mark `status: aligned`. Tony reads it as the frame; he can argue specific decisions but not redraw the family without escalating.
+
+## Output template
+
 ```markdown
-# Tech Vision
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
 
-## Stack family
-- {Web|Mobile|Hybrid}
+# Tech Vision — {{project_name}}
 
-## Language(s) of record
-- …
+## Stack family
+Next.js-class SSR fullstack on edge, with Supabase Postgres as the system of record.
 
 ## Runtime envelope
-- {Browser|Node|Edge|Native iOS|Native Android}
+| Dimension | Decision |
+|---|---|
+| Language | TypeScript end-to-end |
+| Runtime | Edge (Vercel Edge Functions) + Node (server actions) |
+| Persistence | Supabase Postgres (RLS) + PgBouncer |
+| Deploy target | Vercel for app; Supabase managed for data |
+| Edge vs origin | Edge-first for reads; origin for writes |
 
-## Build vs buy vs borrow
-| Capability | Decision | Why |
-|---|---|---|
-| Auth | … | … |
-| Payments | … | … |
-| Search | … | … |
-| Queues | … | … |
-| Analytics | … | … |
+## Build / buy / borrow
+| Capability | Decision |
+|---|---|
+| Auth | Buy — Supabase Auth |
+| Payments | Buy — Stripe |
+| Search | Buy — Algolia (1st year), revisit |
+| Queues | Borrow — pg_cron + outbox pattern |
+| Analytics | Borrow — PostHog OSS |
+| Email | Buy — Resend |
 
 ## Non-negotiables
-- …
+1. PII (incl. emails) stored in the user's region only.
+2. p95 server response ≤ 200ms in the user's region.
+3. Single auth identity per human (no shadow accounts).
+4. On-call rotation never exceeds 0.5 pages/eng/week.
+
+## Deferred
+- Multi-region writes: revisit when EU active users > 2k.
+- Native mobile clients: revisit when web TTI > 4s on > 20% of sessions or PRD demands offline.
 
-## Deferred (revisit when)
-- … (trigger: …)
+## Constraints that drove this
+- Brief constraint #2 (LGPD/GDPR) ruled out global-replica DBs.
+- PRD goal G1 ruled in edge-first reads.
+- Hiring tail in TypeScript ruled out Compose Multiplatform.
 ```
+
+## Anti-patterns Fury rejects
+
+- **Picking a library here.** That's Tony. Pick the *family*.
+- **Non-negotiables that are aspirations.** "Always 100% uptime." Wrong. "Error budget ≤ 0.1% in EU region."
+- **Deferred items with no trigger.** That's procrastination.
+- **A non-negotiable that contradicts a PRD constraint silently.** Surface it, escalate it, decide it.
+
+## Hand-off
+
+> Tech vision at `.wize/planning/tech-vision.md`. Tony, build the architecture inside this frame. Hill, scope the PRD against the non-negotiables (item 1 means the global launch is back on the table only after EU baseline holds). Hawkeye, pick gate granularity assuming `policy = advisory`.

package/src/method-skills/4-implementation/wize-code-review/workflow.md

@@ -3,22 +3,117 @@ code: wize-code-review
 name: Code Review
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri (peer Shuri — done at PR open time)
-status: stub
+status: ready
 ---
 
 # Code Review
 
-**Goal.** Self/peer review focused on code health. Separate from Hawkeye's story review.
+**Goal.** Audit **code health** on the PR. Separate from Hawkeye's `tea-review` (which audits AC fulfillment). Both run on every story PR; they're complementary.
+
+Shuri reviews peer PRs. Tony reviews when architecture is at stake.
+
+## When to run
+
+Every PR that ships code. Quick-dev PRs get a lighter review (skip code-architecture checks unless they touched architecture).
+
+## Inputs
+
+- The PR (diff + tests).
+- Story file (for context — what the PR is supposed to accomplish).
+- Linked design system (when components change).
+
+## Output
+
+- Inline comments on the PR.
+- Final review verdict: `approve` / `request-changes` / `comment`.
 
 ## What this checks
-- Naming, structure, dead code
-- Test coverage and quality (not just presence)
-- Security obvious-misses
-- Performance obvious-misses
-- Architectural drift (call Tony if found)
+
+### Naming + structure
+- Are types, functions, variables named for **what they are**, not **how they're used**?
+- Are files in the right folder per the architecture?
+- Are exports minimal? Module boundaries respected?
+- Are there new abstractions justified by the story or premature?
+
+### Tests
+- Do tests cover the changed behavior (not just coverage %)?
+- Are they fast and isolated?
+- Are mocks at the boundary, not inside the unit?
+- Any `test.skip` / `.only` left in?
+
+### Security (obvious-misses)
+- Input validation at boundaries.
+- Tokens / secrets / PII never logged.
+- SQL parameterized, not concatenated.
+- New deps audited; no known CVEs introduced.
+- Auth context checked on every server entry point.
+
+### Performance (obvious-misses)
+- No N+1 queries.
+- No `await` in tight loops without batching.
+- No new sync I/O on hot paths.
+- Bundle delta acceptable (size of new front-end imports).
+
+### Architectural drift
+- Story didn't quietly introduce a new layer / new pattern.
+- If it did, an ADR was opened or a comment justifies it.
+- Components reused from design system; new components added to system if reusable.
+
+### Style + convention
+- Follows lint / format / type rules.
+- Comments explain *why*, not *what*.
+- Dead code removed.
+- TODOs have an owner + a ticket.
 
 ## What this does NOT check
-- AC fulfillment — that's Hawkeye's `trace` + `review` + `gate`.
 
-## Outputs
-- Inline comments / suggestions on the diff.
+- Whether ACs are met — that's Hawkeye's `tea-review`.
+- Whether the design is right — that's reviewed in pull-request walk-through, ADR review, or party-mode.
+
+Don't conflate. Two reviewers, two scopes.
+
+## Comment style
+
+Use these prefixes:
+
+| Prefix | Meaning |
+|---|---|
+| `nit:` | Cosmetic; non-blocking |
+| `q:` | Question; might be a misunderstanding |
+| `praise:` | Real call-outs; teams need them |
+| `suggestion:` | Idea, the author decides |
+| `blocking:` | Must change before merge |
+| `out-of-scope:` | Real issue, separate story |
+
+Never `LGTM` without scanning. Never `LGTM` with `blocking:` open.
+
+## Verdict
+
+- **approve** — all blockings resolved.
+- **request-changes** — at least one `blocking:`.
+- **comment** — reviewed, no opinion (rare; used for early-draft PRs).
+
+## PR-open checklist (Shuri's self-review)
+
+Before opening, Shuri runs through:
+
+- [ ] CI green locally.
+- [ ] Lint + format clean.
+- [ ] Type-check clean.
+- [ ] No `console.log` / `dbg!` / debug printf.
+- [ ] No `test.skip` / `.only`.
+- [ ] Reading the diff right now, can I explain every line?
+- [ ] Self-walk: open the changed screen / call the changed endpoint.
+- [ ] Story status flipped to `ready-for-review`.
+
+## Anti-patterns Shuri rejects in herself
+
+- Approving without reading.
+- Approving on the basis of green CI alone.
+- "Big PR; will trust" — refuse and ask for slicing.
+- Inline suggestions for full rewrites — open a follow-up instead.
+- Demanding stylistic preferences not in the lint config.
+
+## Hand-off
+
+> Reviewed PR #418 (E02-S02). 2 nits, 1 blocking on auth-context check missing in one new route. Shuri to fix; re-review needed; then Hawkeye runs `tea-review`.