@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/ux-migration/SKILL.md

@@ -0,0 +1,424 @@
+---
+tier: lite
+name: ux-migration
+description: "Compare existing UX to a target treatment, then plan the migration \u2014 branching strategy, feature flags, cutover checklist. Run after /riff-prototypes picks a direction."
+problem: "New UX treatments land alongside old ones. Migration strategy gets improvised per screen."
+value: "Compares existing UX to a target treatment. Plans the migration \u2014 branches and feature flags."
+inputs: [Current UX ref, Target treatment ref]
+outputs: [Migration plan with phases, Feature flag strategy, Branching sequence]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# UX Migration
+
+Plan the migration from an existing UI treatment to a new one. Produces a
+gap analysis, file-level migration plan, branching strategy, and cutover
+checklist — all designed for dual-running so the existing app is never
+disrupted.
+
+## When to run
+
+After `/riff-prototypes` selects a winning variant and before Construction
+begins on the redesign. This skill bridges "we picked a direction" to
+"here's exactly how to get there."
+
+## When this skill fires (and when it doesn't)
+
+This skill is a **MUST gate for redesigns** — when a prototype exists AND
+there's an existing UI to migrate FROM. Skipping this is how overnight
+builds produce correct structure with the wrong visual language.
+
+**Skip for greenfield.** If there's no existing UI (new app, new pages
+with no predecessor), the prototype IS the spec. The Builder builds
+directly from prototype + design tokens. No migration needed because
+there's nothing to migrate from.
+
+| Scenario | Prototype? | Existing UI? | /ux-migration? |
+|---|---|---|---|
+| Redesign existing pages | Yes | Yes | **MUST** — component-level diff |
+| Greenfield build | Yes | No | **Skip** — prototype is the spec |
+| Incremental feature | No | Yes | **Skip** — no visual direction change |
+| Greenfield, no prototype | No | No | **Skip** — use tokens + luminaries |
+
+## Prerequisites
+
+- A selected prototype variant (from `/riff-prototypes` or operator decision)
+- Access to the existing codebase (running app or file system)
+- Design tokens / creative brief from Creative Director. When tokens are
+  not yet authored, BLOCK and surface a `/promote` candidate for the
+  missing token surface; do not proceed with ad-hoc visual choices.
+- Playwright MCP: screenshot BOTH the current state AND the prototype for
+  side-by-side comparison in the gap analysis. When Playwright MCP is not
+  available, BLOCK with `INSTEAD: enable Playwright MCP before continuing` —
+  do not proceed without visual baseline.
+
+## Procedure
+
+### Step 0: Read the sources end-to-end (MANDATORY gate)
+
+Before producing any inventory, gap analysis, or target state, read
+every existing surface file end-to-end. Not skim — read. Record:
+
+```
+## Sources read (ux-migration)
+
+- src/app/[route]/page.tsx (L1-L[end]) — what's there
+- src/components/[Component].tsx (L1-L[end]) — what's there
+- design/design-tokens.css (L1-L[end])
+- docs/prototypes/[selected]/index.html (L1-L[end]) — target reference
+
+## Sources deliberately NOT reading (with reason)
+- [path] — [reason: e.g. out of scope for this migration]
+```
+
+This gate prevents "pattern-matched on generic [X]" failures. The
+migration plan is a derivative of specific files; the specific files
+must be in context before the derivative is produced.
+
+See `.claude/rules/artifact-ingestion.md` — this is the skill-level
+instantiation of that rule for UX migrations.
+
+### Step 1: Inventory the Current State
+
+Map every UI surface that will change:
+
+```markdown
+## Current State Inventory
+
+| Surface | Route/Path | Key Components | Data Dependencies | Screenshot |
+|---------|-----------|----------------|-------------------|------------|
+| Deal list | /deals | DealTable, StatusBadge, Filters | deals API, filters | [link] |
+| Deal detail | /deals/[id] | DealHeader, Timeline, Scores | deal API, scores | [link] |
+```
+
+For each surface:
+1. List the route/path
+2. List key components (grep for exports in the file tree)
+3. List data dependencies (API calls, queries, state)
+4. Screenshot current state via Playwright MCP. When Playwright MCP is not enabled, BLOCK and surface `INSTEAD: enable Playwright MCP before continuing`.
+
+### Step 1b: Capabilities Inventory (what must survive)
+
+Before designing the new treatment, inventory what the old pages DO —
+not just how they look. This is the step that prevents "spec described
+what to build, not what must survive."
+
+For each surface in the current state inventory, list every functional
+capability:
+
+```markdown
+## Capabilities Inventory
+
+| Surface | Capability | Implementation | Must survive? | Notes |
+|---------|-----------|----------------|---------------|-------|
+| Pipeline | Text search filters results | SearchInput + query param | YES | Core workflow |
+| Pipeline | Sort by column header | Sortable table headers | YES | Power user essential |
+| Pipeline | Track filter (1031/Operating) | Filter dropdown | YES | Domain-specific |
+| Pipeline | Pagination | Page buttons | YES | >100 deals |
+| Pipeline | Deal row links to detail | Row click handler | YES | Navigation |
+| Shortlist | Search contacts | SearchInput | YES | |
+| Shortlist | Sortable columns | Table headers | YES | |
+| Deal detail | Score breakdown visible | ScoreBadge components | YES | Key decision data |
+| Deal detail | Financial data formatted | FinancialGrid | YES | |
+```
+
+**How to build this list**:
+1. Open each existing page
+2. Interact with every control: click headers, type in search, use
+   filters, click links, expand sections
+3. Record what happens — each interaction that produces a result is a capability
+4. Mark whether it must survive the migration (almost always YES unless
+   the capability is being intentionally removed with documented rationale)
+
+**This table becomes the Tier 2 test plan** for `/synthetic-user` testing
+after the migration. Every capability marked "must survive" gets a
+feature parity test.
+
+**If a capability is intentionally removed**, document WHY in the Notes
+column. Undocumented removals are bugs, not decisions.
+
+### Step 2: Inventory the Target State
+
+Map the same surfaces in the target treatment:
+
+```markdown
+## Target State (from selected variant)
+
+| Surface | Changes | New Components | New Data Needs | Design Reference |
+|---------|---------|----------------|----------------|-----------------|
+| Deal list | Card layout, new filters | DealCard, QuickActions | + scoring API | prototype-variant-2 |
+| Deal detail | Redesigned header, tabs | TabNav, ScoreRadar | + enrichment API | prototype-variant-2 |
+```
+
+### Step 3: Gap Analysis
+
+For each surface, produce a detailed gap:
+
+```markdown
+## Gap Analysis
+
+### [Surface Name]
+
+**Layout changes**: [grid → cards, sidebar → tabs, etc.]
+**Component-level visual diff** (REQUIRED — this is where builds fail):
+  For EACH component on this surface, state what changes visually:
+
+  | Component | Current | Target | Action |
+  |-----------|---------|--------|--------|
+  | ScoreBadge | Green circle, "73 OVERALL" | Plain number, no badge | REWRITE |
+  | ScoreBreakdown | Colored pills (Price 86...) | Horizontal bars + numeric | REWRITE |
+  | Financials | Spread label-above-value | Dense grid, 2-3 lines | MODIFY |
+  | NavSidebar | Nav links only | Nav + "THIS DEAL" anchors + "RELATED" links | MODIFY |
+
+  Every visual element must appear in this table. If a component is
+  unchanged, mark it KEEP. If the prototype shows something the current
+  build doesn't have, mark it CREATE. This table becomes the Builder's
+  checklist — if it's not in the table, it won't get built.
+
+**Component changes (structural)**:
+  - KEEP: [components unchanged]
+  - MODIFY: [components that need visual/structural updates per table above]
+  - CREATE: [new components needed]
+  - REMOVE: [components no longer used]
+**Data changes**:
+  - New API calls: [list]
+  - Modified queries: [list]
+  - New state: [list]
+**Token changes**:
+  - Colors: [specific token changes]
+  - Typography: [specific token changes]
+  - Spacing: [specific token changes]
+**Responsive breakpoints** (REQUIRED):
+  For each surface, specify behavior at each breakpoint:
+
+  | Breakpoint | Layout change |
+  |---|---|
+  | ≥1024px (desktop) | Full sidebar + content area |
+  | 768-1023px (tablet) | [sidebar collapses? content reflows?] |
+  | <768px (mobile) | [sidebar becomes hamburger/sheet? tables become cards? grids stack?] |
+
+  If the prototype doesn't specify mobile behavior, the migration spec
+  MUST define it before construction. "Same as desktop but smaller" is
+  not a responsive strategy — a 220px sidebar on a 375px phone is broken.
+
+**Risk**: [LOW/MEDIUM/HIGH — based on blast radius and shared component impact]
+```
+
+### Step 3b: Design Token Extraction
+
+Extract concrete values from the prototype HTML into a token reference.
+The prototype uses inline Tailwind classes — those values must be explicit
+so the Builder applies consistent values, not guesses from reading HTML.
+
+```markdown
+## Design Tokens (extracted from prototype)
+
+### Typography
+- Base font size: 13px
+- Numbers: monospace (font-mono)
+- Section headers: uppercase, 10px, tracking-wide, text-muted
+- Page title: text-xl, font-semibold
+
+### Layout
+- Sidebar: fixed 220px, border-r
+- Content: ml-[220px], max-w-5xl
+- Page padding: px-6 py-4
+
+### Chrome
+- Borders: border (1px solid), no rounded corners on data elements
+- Badges: none — plain text with color only
+- Separators: thin horizontal rules (border-t)
+- Shadows: none on content, subtle on sidebar only
+
+### Colors
+- Score high (7+): text-emerald-600
+- Score mid (5-6): text-amber-600
+- Score low (<5): text-red-600
+- Muted labels: text-muted-foreground
+- Links: text-primary, no underline until hover
+```
+
+### Step 3c: Prototype → React Component Mapping
+
+Map each visual element in the prototype HTML to the React component
+it should become. The prototype is static HTML + Tailwind. The build
+is React + shadcn. This table prevents the Builder from guessing.
+
+```markdown
+## Component Mapping
+
+| Prototype element | React component | shadcn base | Action |
+|---|---|---|---|
+| `<table class="w-full">` | PipelineTable | shadcn Table | CREATE using shadcn |
+| `<nav class="w-[220px]">` | SidebarNav | shadcn Sidebar | CREATE using shadcn |
+| `<div class="score">78</div>` | ScoreDisplay | — (too simple) | CREATE custom |
+| Score bar `<div class="h-2 bg-emerald">` | ScoreBar | — | CREATE custom |
+| `<div class="grid grid-cols-3">` financials | FinancialGrid | — | MODIFY existing CompactFinancials |
+| Sidebar "THIS DEAL" anchors | DealSidebarNav | — | CREATE custom |
+| Sidebar "RELATED" links | RelatedLinks | — | CREATE custom |
+```
+
+### Step 4: Migration Plan
+
+Order the work into atomic work packages, respecting dependencies.
+The first work package MUST be foundation (utilities, tokens, shadcn init)
+before any page work starts:
+
+```markdown
+## Migration Plan
+
+### Phase 1: Foundation (no user-visible changes)
+- Branch: feature/ISSUE-NNN-stack-1-design-tokens
+  - Update/add design tokens for new treatment
+  - Feature flag: `NEW_TREATMENT_ENABLED` (default: false)
+  - Risk: LOW — tokens are additive, no existing code changes
+
+### Phase 2: New Components (behind feature flag)
+- Branch: feature/ISSUE-NNN-stack-2-new-components
+  - Create new components: [list]
+  - All gated behind feature flag
+  - Risk: LOW — new files only, nothing existing changes
+
+### Phase 3: Dual Routes (parallel running)
+- Branch: feature/ISSUE-NNN-stack-3-dual-routes
+  - Add parallel routes: /deals-v2, /deals/[id]-v2 (or flag-gated within existing routes)
+  - Wire new components to data
+  - Risk: MEDIUM — new routes, but existing routes untouched
+
+### Phase 4: Cutover Preparation
+- Branch: feature/ISSUE-NNN-stack-4-cutover
+  - Flag flips: new treatment becomes default
+  - Old treatment accessible via flag override
+  - Risk: MEDIUM — user-facing change, but reversible
+
+### Phase 5: Cleanup (after bake period)
+- Branch: feature/ISSUE-NNN-stack-5-cleanup
+  - Remove old components, old routes, feature flag
+  - Risk: LOW — removing dead code after verification
+```
+
+### Step 5: Branching Strategy
+
+Produce a branch stack manifest per `standards/branch-stacking.md`:
+
+```markdown
+## Branch Stack Manifest
+
+stack_id: ux-migration-[surface]
+created: [date]
+issue: #[NNN]
+parallel_safe: [list which branches can run in parallel]
+
+| # | Branch | Depends On | Touches | Parallel-Safe |
+|---|--------|-----------|---------|---------------|
+| 1 | stack-1-design-tokens | — | tokens/ | Yes |
+| 2 | stack-2-new-components | 1 | components/ | Yes (with 1 merged) |
+| 3 | stack-3-dual-routes | 2 | app/, components/ | No |
+| 4 | stack-4-cutover | 3 | app/, config/ | No |
+| 5 | stack-5-cleanup | 4 + bake period | all changed files | No |
+```
+
+### Step 6: Dual-Running Architecture
+
+Reference ADR-012 (dual-running pattern) and specify:
+
+```markdown
+## Dual-Running Plan
+
+**Flag name**: `NEW_[SURFACE]_TREATMENT`
+**Flag mechanism**: [env var / database / config file]
+**Rollout plan**:
+  1. Operator only (internal testing)
+  2. Specific roles (e.g., ADMIN, OPERATOR)
+  3. All users (full rollout)
+  4. Remove flag (cleanup phase)
+
+**Verification at each stage**:
+  - Run /visual-review on new treatment
+  - Run /smoke-test on both treatments
+  - Check analytics: error rates, engagement, performance
+
+**Rollback procedure**:
+  - Flip flag back to false
+  - No code deployment needed
+  - Old treatment resumes immediately
+
+**Bake period**: [recommended duration before cleanup — typically 1-2 weeks]
+```
+
+### Step 7: Output the Migration Spec
+
+Write the complete migration spec to `docs/specs/ux-migration-[surface].md`:
+
+```markdown
+# UX Migration Spec: [Surface]
+
+## Summary
+[1-2 sentences: what's changing and why]
+
+## Current → Target
+[Side-by-side summary]
+
+## Gap Analysis
+[From Step 3]
+
+## Migration Plan
+[From Step 4]
+
+## Branch Stack
+[From Step 5]
+
+## Dual-Running
+[From Step 6]
+
+## Acceptance Criteria
+- [ ] New treatment matches selected prototype variant
+- [ ] /visual-review passes on new treatment
+- [ ] Feature parity: all capabilities from Step 1b inventory verified (100%)
+- [ ] /synthetic-user Tier 2 passes on new treatment
+- [ ] Old treatment unchanged when flag is off
+- [ ] Rollback works within [X] seconds
+- [ ] /smoke-test passes on both treatments
+- [ ] Performance: new treatment ≤ 10% slower than old
+```
+
+### Step 8: Visual Pass Complete Gate
+
+After ALL work packages are implemented, run a final verification:
+
+```markdown
+## Visual Pass Complete — Prototype vs. Build
+
+| Page | Prototype screenshot | Build screenshot | Match? | Gaps |
+|------|---------------------|-----------------|--------|------|
+| Overview | [link] | [link] | ✅/❌ | [what's different] |
+| Pipeline | [link] | [link] | ✅/❌ | |
+| Deal detail | [link] | [link] | ✅/❌ | |
+| ... | | | | |
+
+### Verdict: PASS / FAIL
+- PASS: all pages match prototype direction (exact pixels not required,
+  fundamental choices must match — tables vs. cards, sidebar vs. top nav,
+  dense vs. spacious, chrome vs. minimal)
+- FAIL: list remaining gaps → file as issues or fix in current session
+```
+
+To run this gate:
+1. Serve the prototype: `npx serve docs/prototypes/variant-N/ -l 3001`
+2. Serve the build: `npm run dev` (port 3000)
+3. Screenshot both via Playwright MCP
+4. Compare side-by-side per page
+5. Produce the pass/fail matrix above
+
+This is the final checkpoint before the branch is ready for review.
+
+## What this skill does NOT do
+
+- Design the new treatment (that's `/riff-prototypes` + Creative Director)
+- Implement the migration (that's the Builder against this spec)
+- Decide which variant wins (that's the operator)
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.