moving

docs/ux-refactor/path-to-9-2026-07-07.md

@@ -0,0 +1,278 @@
+# Path to 9 — premium feel, power usability, habit formation
+### The definitive analysis (2026-07-07, v3 FINAL) · goal: 5 persona judges ≥ 9/10 · founder framing: "premium UX + power feeling → addiction"
+### PATH-2 panel: **5/5 ENDORSED** (predicted-if-executed 8.7–9.0). v3 integrates their 7 endorsement conditions. This is the agreed, executable path.
+
+## 0. Standing and method
+
+Evidence base: **7 video-judged rounds (R13–R19), 209 recorded fixes (88 HIGH), 10 shipped
+waves (P–X, merged to main `8ee7ac82`)**, plus the 2026-05-28 addictiveness audit
+(Hook-Model rubric, 7 iterations, 5.0 → 7.7). Scores: video regime avg 7.08 → 7.70
+(Fable ruler), min pinned at 7.5 for three rounds. Two measured plateaus prove the
+polish-wave engine is exhausted: per-round EV ≈ +0.02, and every remaining HIGH ask is
+either structural or systemic — not surgical.
+
+**The panel's own definition of the gap** (R19, 5/5 unanimous, verbatim): *"The product
+has the VISUAL craft of a 9 … but the MOTION identity of a ~7. Gap to 9 is not more
+features or more surfaces — it's a genuine motion system."* Secondary unanimous asks:
+a shown, signature streaming moment; killing the boot interstitial; a systemic AA floor.
+
+What a 9 means per lens (extracted from all 7 rounds' verdicts):
+
+| Judge | Their 9 requires | Their current ceiling-setter |
+|---|---|---|
+| design-director | spatial continuity, spring physics, choreographed transitions, multi-tier hover | "surfaces cut/fade instead of transforming" |
+| knowledge-worker | instant feel (no boot tax, no staged arrival), interactions that telegraph | "make it feel instant"; boot + skeleton dwell on every route |
+| competitor-critic | streaming rhythm at Claude/ChatGPT level + a motion language they lack | "the exact axis the video regime exposes: pure motion signature" |
+| a11y-theme-parity | systemic AA tertiary tier + keyboard-first hover-reveals + hit areas | "systemic dim secondary text… weighs heaviest" (THE min-score gate) |
+| brand-resonance | the hive alive on WORKING surfaces: honey responds to touch, streaming heartbeat, ambient life | "the brand goes quiet on the working surfaces" |
+
+## 1. Why the founder's "addiction" framing and the judges' "motion system" converge
+
+The Hook Model (trigger → action → variable reward → investment) says habit forms when
+each loop is *felt*. The judged deficits map directly onto the loop's felt moments:
+
+- **Action feel** = the power feeling. Instant boot, sub-100ms responses to the cursor,
+  keyboard-first paths — Fogg's "ability" term. Today's boot tax + single-tier hovers
+  make every loop pay a toll; a power user's loop must feel FREE.
+- **Variable reward** = the visible aliveness. Streaming heartbeat, surprise-recall
+  ("I REMEMBER" cards), honey blooming under the cursor — the dopamine surface. Judges
+  keep scoring exactly these as the missing "signature moments."
+- **Investment made visible** = memory counters, growth, compounding identity — the
+  product already OWNS this (Memory Trust 8.2, "category-defining"); it needs the loop
+  to *celebrate* accrual (count-ups, growth deltas in the briefing) rather than list it.
+- **Triggers** are mostly outside the judged surface (digests, notifications) — real for
+  retention, invisible to this panel. They ride the roadmap but not the score.
+
+So: **the same three workstreams that raise the judged score to 9 are the ones that
+manufacture the addiction loop.** There is no tension between the founder ask and the
+panel's path.
+
+## 2. The path — four pillars + a phase-0 vocabulary, sequenced
+
+### PHASE 0 · THE MOTION VOCABULARY (prerequisite; ships FIRST with Pillar 4) — [PATH-1: design blocking #2]
+Before ANY new motion ships (including Pillar 3's aliveness moments):
+1. **One spring FAMILY, not one config** — 2–3 named variants (`micro` / `standard` /
+   `expressive`) sharing a single physical character, tuned once, exported as motion
+   tokens. Kills the mixed CSS-ease/duration zoo. [design non-blocking, adopted]
+2. **A motion-spec reference page** — an internal demo surface where every tier (spring
+   family, hover tiers, settle gesture, route transitions, reduced-motion mappings) is
+   demonstrable and reviewable. The arc's single source of motion truth. [design gap]
+3. **Reduced-motion mapping defined for EVERY tier** (not just ambient): route
+   transitions degrade to crossfade; hover keeps color/shadow, drops translate;
+   settle gesture → instant state + color pulse; streaming caret → static cursor;
+   count-ups → instant set. [design gap + a11y]
+4. **Interruptibility + input-primacy as ACCEPTANCE CRITERIA** [design blocking #1]:
+   every transition is interruptible and redirectable mid-flight; navigation and input
+   NEVER wait on an exit animation or transition completion. The motion system must
+   never fight the instant-feel pillar — this is a per-PR checklist item, not an
+   aspiration.
+5. **Exit choreography in the same vocabulary**: AnimatePresence exit definitions for
+   cards, menus, modals, and route surfaces. [design non-blocking, adopted]
+6. **RETROFIT of already-shipped motion** [PATH-2 design]: inventory every prior
+   motion pass (Wave T/U hover tiers, Wave V lift+bloom + theme crossfade, Wave W
+   entrance stagger, onboarding/streaming breathing) on the motion-spec page, then
+   migrate each onto the Phase-0 tokens and spring family. Acceptance: ZERO
+   non-token durations/easings on judged surfaces — one motion dialect, not two.
+7. **Signature-moment frequency/intensity taxonomy** [brand blocking #2 + design/kw
+   non-blocking — 3 judges independently]:
+   - FULL settle (300–400ms): rare accrual milestones ONLY — memory saved (first per
+     session), install success, agent spawned.
+   - MICRO variant (≤150ms, same gesture DNA): high-frequency actions — send-arm,
+     selection.
+   - Per-session cooldowns on full-amplitude moments; routine actions never flourish.
+
+### Pillar 1 · THE MOTION SYSTEM (structural; the unanimous #1; est. +0.6–0.9 panel-wide)
+A dedicated engineering arc, NOT lanes. Builds ON the Phase-0 vocabulary.
+
+1. **Spatial continuity — a base tier everywhere + two heroes** [PATH-2 design]:
+   (a) DEFAULT tier: a low-risk fade-through crossfade with persistent chrome
+   (150–200ms, Phase-0 `standard` spring) on ALL top-level sidebar route changes,
+   feature-flagged, subject to the Phase-0.4 interruptibility criteria — the
+   Settings↔Home pair is the template, not a one-off. Two morphs + five hard cuts
+   would read as three set pieces, not a system.
+   (b) HERO morphs (the only shared-element cases): card→workspace-open (the card
+   grows into the surface) and Trust↔Memories tab morph. Implementation:
+   framer-motion `layoutId` + `AnimatePresence mode="popLayout"` scoped to these
+   two (NOT a global router rewrite — that's the regression trap).
+   **Focus + assistive-tech spec ships INSIDE the transition component** [a11y
+   blocking #1]: on every shared-element route change, focus moves to the destination
+   surface's primary heading/main landmark; exiting AnimatePresence trees are set
+   `inert`/`aria-hidden` for their exit duration (focus and the SR virtual cursor can
+   never land in them); route changes are announced (document.title update + a polite
+   live region).
+2. **Multi-tier hover — "honey responds to touch"**: rest → hover (120–160ms: lift
+   2-4px + shadow + honey border-warm + glow bloom) → press (scale .98) →
+   focus-visible (same tier, keyboard). ONE implementation (a `hive-interactive`
+   variant), adopted by cards, rows, chips, tiles. Can ship early (additive).
+3. **The signature gesture — commissioned as a DESIGNED MOTION ASSET** [brand
+   blocking #1]: a recognizably waggle-derived micro-choreography (brief directional
+   waggle-run → settle, from the bee's actual figure-eight dance), prototyped and
+   judged STANDALONE on exactly one moment (memory saved) BEFORE any propagation.
+   Only after the panel scores the prototype does it roll out per the Phase-0
+   frequency taxonomy. Highest-upside, highest-kitsch-risk line in the path —
+   treated accordingly.
+4. **Ambient hive life**: the breathing glow (already shipped on onboarding, judged
+   "the one unambiguously signature motion") recurs as idle ambient on Home hex-glow
+   and empty states. Amplitude discipline: ambient means BELOW attention threshold.
+5. **Light-theme variants for every glow/bloom signature** [brand]: deeper honey,
+   tighter radius on ivory — the signatures must not vanish (or smear) in light.
+   Kit v6 captures each signature moment in BOTH themes.
+6. **P1/P2 seam**: cache-first warm paint lands with one subtle designed micro-settle
+   rather than a raw instant pop. [design non-blocking, adopted]
+
+### Pillar 2 · THE INSTANT POWER FEEL (perceived performance; est. +0.3–0.5, biggest for kw/competitor)
+1. **Kill the returning-user boot tax**: warm sessions land on content <1s (brand
+   flash ≤500ms). Cache-first paint: the Home payload cache is **disk-persisted and
+   renders BEFORE the sidecar answers** — the day-30 morning desktop launch is the
+   moment that matters, not just SPA revisits. [kw gap, adopted]
+2. **The input-during-warmup CONTRACT** [PATH-2 kw]: cache-first paint must be
+   INTERACTIVE, not just visible — (a) the composer accepts typing at paint; queued
+   sends dispatch when the sidecar is ready (never error, never silently drop);
+   (b) first click on any cached card either acts or shows a truthful per-element
+   pending state — never a dead click. The §3 hard gate measures time-to-first-
+   INTERACTION, not just time-to-content, and kit v6 records a cold-start variant
+   (sidecar down → app start → cached paint → first send).
+3. **The silent-refresh reconciliation CONTRACT** [kw blocking]: when fresh data lands
+   over a cache-first paint — (a) NO above-the-fold layout shift; (b) material deltas
+   animate in via the Pillar 3.3 delta pulse instead of silently replacing content;
+   (c) the briefing modal (reserved for ≥7-day absences — N=7, decided) renders from
+   the SAME data source/component as the home hero cards, killing the number-drift
+   bug class permanently. Wrong-then-corrected is worse than slow; the contract is a
+   test, not a guideline.
+4. **Collapse the double catch-up**: the "I REMEMBER" cards land INSIDE the home hero
+   as the first staggered entrance; the modal fires only on ≥7-day absences (same
+   component, same data — see 2.2).
+5. **The send-path budget** [kw gap, adopted]: the single most repeated daily action
+   (send → first token) gets an explicit instant contract — optimistic user-bubble
+   echo, composer never locks on send, first-token latency never increased by any
+   visual layer.
+6. **Route-cache everything judged**: chat thread, marketplace, agents join memory/
+   workspaces — tab returns instant, no re-skeleton. Marketplace's first-match wait
+   keeps its purpose-built skeletons (banked residual, R17). [kw]
+7. **Keyboard-power layer**: focus-visible parity on every hover-reveal (kebab +
+   memory rows remain), ~40px hit areas, a ≤2-keystroke path from anywhere to
+   new-chat / last-workspace, and a discoverable shortcut cheat sheet (`?` / Cmd-/).
+   [kw non-blocking, adopted] Double yield: this is also the a11y judge's #2 ask.
+
+### Pillar 3 · THE ALIVENESS LOOP (variable reward made visible; est. +0.3–0.5, brand/competitor)
+1. **Streaming as a PIPELINE deliverable, then a visual one** [competitor blocking #1]:
+   first resolve the dev echo-provider's whole-block behavior — emit true token/chunk
+   streaming in the judged environment, or add a render-side cadence buffer that
+   smooths chunks into a steady visible rhythm with ZERO added latency to first token.
+   Acceptance: recorded s04 shows continuous sub-line accretion — no multi-second
+   block pops, no layout jank as markdown forms. THEN the branded layer: the
+   **streaming text caret** — a honey glow trailing the accreting text head (this is
+   what "bee-trail cursor" means; it is NEVER a pointer-following trail [brand
+   blocking #3]) + a subtle thinking pulse on the bee avatar during tool-trace.
+   Reduced-motion: static caret, no pulse. The caret never occludes text or targets.
+   [a11y] **Streaming INTERACTION contract** [PATH-2 competitor]: auto-follow scroll
+   breaks INSTANTLY on user scroll (input-primacy applied to the stream) with a
+   "jump to latest" affordance; a visible stop control halts output immediately;
+   the recorded s04 acceptance prompt forces hard-case progressive rendering (a
+   code block + a list/table) — markdown formation tested where Claude's streaming
+   craft is strongest.
+2. **Surprise-recall as a first-class moment**: when Auto Recall lands mid-chat, the
+   memory chip blooms honey for ~600ms ("reward of the hunt", rubric dim 6 — the
+   product's unique dopamine no competitor can copy).
+3. **Investment celebration with an HONESTY GATE** [brand non-blocking, adopted]:
+   count-ups and "+" delta pulses bind to the exact source-of-truth number — the
+   settled value is never floored, clamped, or estimated (regression-tested); animation
+   intermediates must never contradict a visible sub-stat (the Wave X lesson,
+   generalized). Briefing states what ACCRUED since last visit ("12 new memories ·
+   2 decisions"). Accessible treatment: one polite live announcement of the settled
+   number, never intermediate frames. [a11y]
+4. **First-60s wow** (rubric dim 3): wire the first chat message to demonstrably use
+   the just-typed profile ("As a consultant, you'll want…") — the "it already knows
+   me" hook.
+
+### Pillar 4 · THE AA FLOOR (systemic; unblocks the min-score judge; est. min 7.5→8+)
+1. **Token-level tier**: define a `--text-tertiary` tier that is AA on EVERY surface
+   token (bg/bg-2/surface/surface-2) in BOTH themes; migrate the ~dozen recurring
+   offender families (top utility bar, timestamps, card meta, onboarding subtitle/
+   footnote, unselected chips).
+2. **Close the GENERATION vector, not just today's instances** [a11y blocking #2]:
+   (a) a lint/CI guard banning new non-token text colors (raw hex, palette classes,
+   arbitrary values) on app surfaces; (b) contrast verification that models
+   COMPOSITION — opacity-modified text and text over wallpaper/gradient/wash measured
+   against effective background (a runtime axe-style pass on the judged surfaces).
+   Token-pair math alone buys one clean round; this buys a floor.
+3. **The AFFORDANCE floor** [PATH-2 a11y]: non-text contrast (WCAG 1.4.11, ≥3:1
+   against adjacent effective background, both themes) for focus indicators,
+   input/chip borders, and state glyphs — a `--focus-ring`/border tier alongside
+   `--text-tertiary`, asserted in the same CI runtime pass. Explicit acceptance:
+   Pillar 1.2's focus-visible tier passes 3:1 in LIGHT (honey-on-ivory), MEASURED.
+4. Hit-area and focus-visible items fold into Pillar 2.7 (double-yield, one
+   implementation).
+
+## 3. Sequencing, risk, verification
+
+**Order: Phase-0 + Pillar 4 (parallel, both token-level, zero-regression) → Pillar 2 →
+Pillar 3 → Pillar 1** — with Pillar 1.2 (hover grammar) allowed early as additive.
+Amended from v1: the motion vocabulary now PRECEDES all aliveness work. [design blocking #2]
+
+**Competitive teardown at arc start** [competitor non-blocking, adopted]: record the
+equivalent journeys on current Claude and ChatGPT (spot-check Hermes/Odyssey); extract
+concrete numeric targets — warm time-to-content, visible token rhythm, transition/hover
+timings. "At Claude/ChatGPT level" becomes measured, not remembered.
+
+Risks: route transitions carry regression risk (scoped routes, feature-flag, the
+Phase-0.4 interruptibility criteria, the P1.1 focus/AT spec); streaming choreography
+must never delay tokens (P2.4 budget); ambient motion must never read as busy (brand:
+"respectful, no gratuitous movement" is currently a WIN — don't lose it).
+
+**Verification — kit v6** [design blocking #3 + competitor blocking #2 + a11y blocking #3]:
+- Judges pinned `model:'fable'` (ruler stability; the R19 lesson).
+- **Per-journey sampling matched to the deliverable, disclosed in the judge brief**:
+  transition/signature/streaming journeys delivered as ≥12fps micro-filmstrips or
+  short native-framerate clips (spring character, token cadence, and settle
+  choreography are invisible at 2–4fps — the arc's history proves measurement
+  failures eat rounds); 2fps contact sheets remain for static-composition journeys.
+- **A keyboard-only journey**, recorded and judged like the mouse journeys: tab-through
+  home → open workspace → chat send → message actions via focus → memory row actions →
+  settings, visible focus indicators expected in every frame.
+- **Warm time-to-first-INTERACTION as a HARD gate**: Playwright-measured, fails the
+  round if >1000ms to interactive content / >500ms brand flash. [kw, PATH-2]
+- **Reduced-motion ENFORCEMENT** [PATH-2 a11y]: an automated Playwright pass with
+  `prefers-reduced-motion: reduce` emulated, asserting the Phase-0.3 mappings per
+  tier (route transitions crossfade-only; no transform animation on hover; settle →
+  instant state; static streaming caret; count-ups set instantly), run per round like
+  the contrast and warm-boot gates — plus one recorded reduced-motion spot-journey.
+- New journeys: send→stream→settle (shipped v5), card→workspace-open transition,
+  tab-morph, warm-boot timing, cold-start-to-first-send, keyboard-only,
+  reduced-motion spot, waggle-settle prototype (standalone, both themes).
+- **Side-by-side clips vs current Claude and ChatGPT** [PATH-2 competitor]: streaming
+  + warm-launch journeys at minimum, from the arc-start teardown footage, refreshed
+  at the 9-attempt round and delivered in the judge brief — parity/beat claims judged
+  from paired evidence, not memory.
+
+Success gates per round: min-of-5 ≥ 8.0 after Phase-0+P4+P2; ≥ 8.5 after P3; 9 attempt
+after P1. If two consecutive rounds plateau below gate → stop, re-analyze (the
+discipline that caught both prior plateaus).
+
+## 4. What we deliberately do NOT do
+- No more polish waves against the old ask lists (measured EV ≈ 0).
+- No gamification-shaped addiction (streaks, badges, FOMO mechanics) — the panel would
+  score it as noise and it contradicts the trust-first brand voice that earns the 8.2s.
+  Addiction here = the loop feeling so good it self-reinforces, not manipulation.
+- No global router rewrite; no motion on the working thread that competes with content;
+  no pointer-following effects of any kind.
+- No unreviewed propagation of the signature gesture: prototype → panel → rollout.
+
+## 5. Panel disposition — AGREED (goal met)
+- **PATH-2** (v2): **5/5 ENDORSE** — design 8.8 (high) · kw 9.0 (medium) · competitor
+  8.8 (high) · a11y 8.7 (high) · brand 9.0 (medium). Seven endorsement conditions →
+  integrated in THIS v3: default route-transition tier + retrofit deliverable
+  (design); input-during-warmup contract + first-interaction gate (kw); streaming
+  interaction contract + side-by-side evidence (competitor); affordance floor +
+  reduced-motion enforcement (a11y). **The panel agrees on the path — v3 is the
+  executable contract for the arc.**
+
+### PATH-1 disposition (for the record)
+v1 review: design 8.7 endorse · kw 8.7 endorse · competitor 8.5 endorse · brand 9.0
+endorse · a11y 8.3 WITHHELD. All 12 blocking amendments integrated above (Phase-0;
+interruptibility; resequencing; silent-refresh contract; streaming pipeline rescope;
+high-framerate verification; focus/AT spec; generation-vector CI; keyboard journey;
+commissioned gesture; frequency taxonomy; caret disambiguation) plus 9 high-consensus
+non-blocking adoptions (spring family, motion-spec page, reduced-motion per tier, exit
+choreography, P1/P2 seam, send-path budget, disk-persisted cache, honesty gate,
+competitive teardown, light-theme signatures, shortcut cheat sheet).