@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/enhance-onboarding/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: enhance-onboarding
+description: >
+  Activation pass: define the activation event, cut steps to first value, add
+  templates, sample data, a short checklist, and signup → activated events.
+  Use when "improve onboarding", "users sign up and leave", or "activation
+  rate".
+license: MIT
+---
+
+# enhance-onboarding — First session to first value
+
+**Degree of freedom: MIXED.** Choosing the activation event and which
+patterns fit `[HIGH freedom]`; the event names, the new-user walkthrough, and
+the before/after step count `[LOW freedom — run exactly]`.
+
+Apply-now. The product already works; two-thirds of the people who sign up
+never see it work (median B2B activation 37%, Userpilot n=62). This skill
+shortens the path from landing to the first real outcome and proves it with
+events, not a tour.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **enhance-onboarding** (this) | Landing → signup → first value → habit, as one journey |
+| `enhance-web-ux` | Any single route's flows and density |
+| `audit-ui-states` | Empty / loading / error states audit (findings) |
+| `enhance-web-forms` | Form structure, validation, a11y |
+| `audit-analytics` | Whether events exist and fire after consent |
+| `enhance-web-conversion` | Pricing, upgrade prompts — after activation |
+| `design-email` | Day-1/3/7 re-engagement mail this skill may request |
+| `plan-gtm` | Decides *what* activation means for the business; this skill builds it |
+
+Do **not** fire for "add a product tour" as stated — tours are a last resort here.
+
+## How to reason
+
+1. **Define** — the activation event is the first outcome the user came for, not signup or tour-end
+2. **Measure** — current steps and drop-off from landing to that event (instrument first if blind)
+3. **Cut** — every field, screen, or decision before the event that can wait
+4. **Guide** — what remains gets a template, sample data, a ≤5-item checklist, or one contextual hint
+5. **Verify** — a fresh user reaches the event in fewer steps; events fire; nothing else regressed
+
+## Worked example
+
+> **Define:** a kakeibo app — `activated` = first transaction categorized, not
+> account created.
+> **Measure:** landing → 6-field signup → email verify → empty dashboard →
+> "Add account" → "Add transaction" = 9 steps, verification email lost on mobile.
+> **Cut:** OAuth + magic link; name/currency inferred from locale; verify later.
+> **Guide:** empty dashboard becomes "Start with sample month" + "Add your first
+> expense"; 3-item checklist ends at the activation event.
+> **Verify:** 9 → 4 steps; `activated` fires on first categorized row; Playwright
+> new-user path green; existing password login untouched.
+
+## Self-critique before reporting
+
+- **Event is value** — `activated` fires on an outcome, never on `signup_completed` or tour end
+- **Steps counted** — before/after step counts are in the report from a real walkthrough
+- **Nothing removed** — every auth provider, setting, and route still exists; fields were deferred, not deleted
+- **Consent-gated** — no event fires before the consent state the app already uses
+- **Right owner** — pricing/upgrade → `enhance-web-conversion`; single-route polish → `enhance-web-ux`
+
+---
+
+## Procedure
+
+### 1. Define activation  [HIGH freedom]
+
+Reforge order: **Setup** (must-have info) → **Aha** (core value once) →
+**Habit** (core action at its natural frequency). `activated` is the aha. Pick
+it by asking: *what did they come to do, and when have they done it once?* One
+event, written as `activated` plus the domain event that triggers it (e.g.
+`transaction_categorized`). Add `setup_completed` and `habit_reached` (e.g. 3
+sessions in 7 days) so setup drop-off and retention are measurable too. When
+analytics already exist, prefer the event combination that best predicts
+3-month retention; a valid activation event shows ≥ 2× retention for the users
+who hit it. Payment is never the activation event.
+
+### 2. Measure the current path  [LOW freedom — run exactly]
+
+1. Fresh browser profile (or emulator) — walk landing → activation as a stranger.
+2. Record each step: URL, fields, decisions, waits (email, verification, payment).
+3. Pull funnel numbers if analytics exist; otherwise write **unmeasured** and
+   add instrumentation in step 4 before any redesign is judged.
+
+Benchmarks for judging (sources in `plan-gtm/references/benchmarks-2026.md`):
+median B2B activation 37%, good = p60 / great = p80 for the product type;
+time-to-value over 24 h → activation collapses below 25%; top quartile first
+value under 5 minutes; day-7 return ≥ 7% of a new cohort is top quartile.
+Checklist completion averages ~19% (engaged users finish ~5 items) — a
+checklist supports the path, it does not replace cutting it.
+
+### 3. Cut and guide  [HIGH freedom — choose; each pattern below is optional]
+
+| Do | Avoid |
+|---|---|
+| Try before signup when the value shows in one session (7% of self-serve products now lead ungated; value-before-signup lifts referred conversion 2–5×) | Signup wall in front of a demo |
+| OAuth / magic link; password as fallback; one optional "how did you hear about us" field | 6+ field forms, phone, company size |
+| Infer locale, currency, timezone; ask firmographics after first value | Profile wizard before the product |
+| Empty state = one primary action + "start from a template / sample data" | Blank screen with a "+" icon |
+| ≤5-item checklist, open by default, first item pre-completed, completion detected by real events, last item **is** the activation event | 12-item tour of every menu |
+| Guidance embedded in the UI (+20% engagement vs modals); tours only user-triggered and ≤4 steps (67% completion vs 31% timer-triggered; 7+ steps 16%) | Autoplay tours, modal stacks, welcome videos |
+| Personalize with at most one JTBD question — and use the answer (65% collect it, 18% use it) | Role/industry quiz before value |
+| Day-1/3/7 email nudges tied to unfinished checklist items (→ `design-email`) | Generic "welcome aboard" mail; sales outreach minutes after signup |
+| Keep card-required trials only if `plan-gtm` chose that model | Payment before value by accident |
+
+Deferred fields move to settings or a later prompt; nothing is deleted.
+
+### 4. Instrument  [LOW freedom — names]
+
+Use the app's existing analytics SDK and consent gate. Canonical events:
+
+```
+signup_started · signup_completed { method, source }
+onboarding_step_completed { step }
+setup_completed
+activated { via: <domain_event> }
+habit_reached { sessions, window_days }
+```
+
+Server-side where possible; same analytics project as the marketing site so
+`page_viewed { utm, referrer }` joins to signup. Reconcile naming with
+`audit-analytics` when a taxonomy already exists. No PII in properties. Fire
+nothing before consent.
+
+### 5. Verify  [LOW freedom — run exactly]
+
+- New-user Playwright path from landing to `activated` — passes, step count ≤ target
+- Existing login providers, settings, and routes — unchanged (regression pass)
+- Events visible in the analytics debug view or test sink
+- Report: steps before/after, TTV estimate, events added, files touched
+
+## Guardrails
+
+- **No dark patterns** — no fake progress, forced card, hidden skip, or pre-checked upsell.
+- **Defer, never delete** — collected data the business needs moves later in the journey.
+- **Do not invent numbers** — funnel cells stay "unmeasured" until events exist.
+- **One journey** — landing to first value; the rest of the app is another skill's.
+
+## Chains with
+
+- **`plan-gtm`** → defines the business meaning of activation; this skill ships it.
+- **`audit-ui-states`** → empty/loading/error findings feed step 3.
+- **`enhance-web-forms`** → the signup form itself.
+- **`enhance-web-conversion`** → upgrade prompts after activation.
+- **`test-playwright`** → lock the new-user path.

package/skills/enhance-pwa/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: enhance-pwa
+description: >
+  Add or upgrade PWA features: manifest, service worker, offline mode, install
+  prompt, push, background sync. Use when "make it a PWA", "offline support",
+  or "install prompt". Native → mobile-capacitor-platform.
+license: MIT
+---
+
+# enhance-pwa — Make It Installable and Offline-Ready
+
+**Degree of freedom: MIXED.** Strategy and prompt timing `[HIGH freedom]`; caching rules, Capacitor bypass, and the installability check `[LOW freedom — run exactly]`.
+
+**A PWA closes the gap between "website" and "app".** Users can install it to
+their home screen, it loads instantly from cache, and it keeps working when the
+network drops. This skill adds those capabilities to any existing web app without
+breaking what already works.
+
+## How to reason
+
+1. **Audit** — manifest, SW, framework plugin already present
+2. **Choose** — caching strategy per asset type; Workbox over raw SW
+3. **Ship** — installable manifest + offline fallback + autoUpdate
+4. **Prove** — DevTools shows no installability errors; offline revisit works; Capacitor bridge not intercepted
+
+## Worked example
+
+> **Audit:** Next.js app; no manifest link; no SW; also ships Capacitor.
+> **Choose:** Serwist (Workbox fork) via `@serwist/turbopack`; NetworkFirst APIs; CacheFirst images; skip `capacitor://`.
+> **Ship:** `manifest.webmanifest` + 192/512 icons + `/offline.html`; install prompt after first success.
+> **Prove:** offline revisit of `/` works; DevTools Manifest pane shows no installability errors; native bridge still functions.
+
+## Self-critique before reporting
+
+- **No stale deploys** — `autoUpdate`, not silent stale cache
+- **No secrets in cache** — auth tokens and sensitive APIs are NetworkOnly
+- **Offline path** — fallback page or cached shell, not a browser error
+- **Right owner** — native Capacitor shell → `mobile-capacitor-platform`; confirm bridge via `mobile-emulator-test`
+
+---
+
+## Phase 0: Audit what already exists  [HIGH freedom]
+
+```
+public/manifest.json or public/manifest.webmanifest  → existing manifest
+public/sw.js or src/sw.ts                             → existing service worker
+vite.config.*   → vite-plugin-pwa already configured?
+next.config.*   → next-pwa or @serwist/* already configured?
+package.json    → workbox-*, serwist, @serwist/*, vite-plugin-pwa, next-pwa, @vite-pwa/nuxt
+```
+
+Also check the basics in the page (Lighthouse 12+ has no PWA category):
+```javascript
+// eval after goto
+const pwaReady = {
+  manifest: !!document.querySelector('link[rel="manifest"]'),
+  sw: 'serviceWorker' in navigator,
+  https: location.protocol === 'https:' || location.hostname === 'localhost',
+};
+```
+
+---
+
+## Phase 1: Research framework-specific PWA tooling  [HIGH freedom]
+
+Follow `/research`: Context7 for the PWA plugin that matches the framework (`vite-plugin-pwa`, `@serwist/turbopack` or `@serwist/next`, `@vite-pwa/nuxt`), Firecrawl for current service-worker and offline guidance. Search the plugin name as written and anchor to the framework version actually installed — recognizing a package is not knowing its current API.
+
+---
+
+## Phase 2: Web App Manifest  [HIGH freedom]
+
+The manifest is what makes the app installable. Create or improve
+`public/manifest.webmanifest`:
+
+```json
+{
+  "name": "Full App Name",
+  "short_name": "Short Name",
+  "description": "One sentence about what the app does",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#6366f1",
+  "orientation": "portrait-primary",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable any" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable any" }
+  ],
+  "screenshots": [
+    { "src": "/screenshots/home.png", "sizes": "1280x720", "type": "image/png", "form_factor": "wide" },
+    { "src": "/screenshots/home-mobile.png", "sizes": "390x844", "type": "image/png", "form_factor": "narrow" }
+  ]
+}
+```
+
+Reference the manifest in `<head>`:
+```html
+<link rel="manifest" href="/manifest.webmanifest" />
+<meta name="theme-color" content="#6366f1" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-status-bar-style" content="default" />
+<link rel="apple-touch-icon" href="/icons/icon-192.png" />
+```
+
+**Icon requirements:**
+- 192×192 and 512×512 minimum; add 180×180 for Apple Touch Icon
+- PNG with transparent background OR maskable (safe zone = inner 80%)
+- Generate from a single source SVG using `sharp` or `pwa-asset-generator`
+
+---
+
+## Phase 3: Service Worker — caching strategy  [HIGH freedom]
+
+Use **Workbox** (via the framework plugin) rather than writing raw service
+worker code. Choose the right caching strategy per asset type:
+
+| Asset type | Strategy | Why |
+|------------|----------|-----|
+| App shell (HTML/JS/CSS) | CacheFirst + revision hash | Fast loads, updated on deploy |
+| API data (list/detail) | NetworkFirst with 5s timeout | Fresh data, offline fallback |
+| Images | CacheFirst, 30-day expiry | Rarely changes |
+| Fonts | CacheFirst, 1-year expiry | Never changes |
+| Analytics/telemetry | NetworkOnly | No value in caching |
+
+### Vite (vite-plugin-pwa)
+
+```typescript
+// vite.config.ts
+import { VitePWA } from 'vite-plugin-pwa';
+
+VitePWA({
+  registerType: 'autoUpdate',
+  workbox: {
+    globPatterns: ['**/*.{js,css,html,ico,png,svg,webp}'],
+    runtimeCaching: [
+      {
+        urlPattern: /^https:\/\/.*\/api\//,
+        handler: 'NetworkFirst',
+        options: {
+          cacheName: 'api-cache',
+          expiration: { maxAgeSeconds: 60 * 60 * 24 },
+          networkTimeoutSeconds: 5,
+        },
+      },
+    ],
+  },
+  manifest: { /* inline or separate file */ },
+})
+```
+
+### Next.js (Serwist, or an existing next-pwa)
+
+Next.js has no built-in service worker. It ships the `app/manifest.ts` file
+convention, and 16.3 added an experimental `experimental.useOffline` flag that
+detects connectivity and retries requests but does not cache pages. For
+Workbox-style caching the Next.js PWA guide points to Serwist, a Workbox fork:
+`@serwist/turbopack` for Turbopack builds (the `next build` default since
+Next.js 16) or `@serwist/next` for webpack builds. Take the setup for the
+installed Next.js version from the Serwist docs.
+
+`@ducanh2912/next-pwa` is webpack-only (last release 10.2.9, September 2024)
+and its README recommends migrating to `@serwist/next`. Keep it only where a
+repo already uses it, and on Next.js 16+ build with `next build --webpack`:
+
+```javascript
+// next.config.mjs
+import withPWA from '@ducanh2912/next-pwa';
+export default withPWA({
+  dest: 'public',
+  cacheOnFrontEndNav: true,
+  aggressiveFrontEndNavCaching: true,
+  reloadOnOnline: true,
+})({ /* rest of next config */ });
+```
+
+### Capacitor compatibility
+
+If the app also ships as a Capacitor native app, the service worker must not
+intercept Capacitor's bridge requests. Add to the service worker:
+
+```javascript
+// Do not cache Capacitor bridge calls
+if (event.request.url.includes('capacitor://') ||
+    event.request.url.includes('ionic://')) {
+  return; // let it pass through
+}
+```
+
+---
+
+## Phase 4: Offline page and graceful degradation  [HIGH freedom]
+
+When the network is unavailable and a cached response does not exist, show a
+helpful offline page rather than a browser error:
+
+```html
+<!-- public/offline.html -->
+<h1>You are offline</h1>
+<p>Check your connection and try again. Pages you have visited recently will still load.</p>
+<button onclick="location.reload()">Try again</button>
+```
+
+Register it as the fallback. Workbox's `navigateFallback` answers every
+non-precached navigation with one HTML file, online or not, so it is the SPA
+shell (vite-plugin-pwa defaults it to `index.html`), not an offline page. For
+server-rendered pages, precache `offline.html` and attach it to the
+navigation route:
+```javascript
+// workbox (generateSW) options; clear the SPA fallback so this route runs
+navigateFallback: null,
+runtimeCaching: [{
+  urlPattern: ({ request }) => request.mode === 'navigate',
+  handler: 'NetworkFirst', // NetworkOnly if pages carry per-user data
+  options: { cacheName: 'pages', precacheFallback: { fallbackURL: '/offline.html' } },
+}],
+// hand-written service worker: offlineFallback() from workbox-recipes
+```
+
+With Serwist (Next.js), precache the page through `additionalPrecacheEntries`
+and list it in the `Serwist` constructor's `fallbacks.entries` with a
+`request.destination === 'document'` matcher.
+
+---
+
+## Phase 5: Install prompt (optional but high-value)  [HIGH freedom]
+
+Do not use the browser's default install prompt — it appears at the wrong time.
+Instead, intercept `beforeinstallprompt` and show it when the user has
+demonstrated value (e.g. after completing a core action):
+
+```typescript
+// hooks/useInstallPrompt.ts
+let deferredPrompt: BeforeInstallPromptEvent | null = null;
+
+window.addEventListener('beforeinstallprompt', (e) => {
+  e.preventDefault();
+  deferredPrompt = e as BeforeInstallPromptEvent;
+});
+
+export function triggerInstallPrompt() {
+  if (!deferredPrompt) return;
+  deferredPrompt.prompt();
+  deferredPrompt.userChoice.then(() => { deferredPrompt = null; });
+}
+```
+
+Show a custom banner with clear benefits ("Install for offline access and faster loads"),
+not just "Add to Home Screen". `beforeinstallprompt` fires only in Chromium browsers;
+Safari (including iOS) and Firefox never fire it, so on iOS show Share → Add to
+Home Screen instructions instead.
+
+---
+
+## Phase 6: Push notifications (if backend supports it)  [HIGH freedom]
+
+Only implement push if the app has a genuine reason to send notifications
+(not just to ask for permission on first load — users will deny that).
+
+```typescript
+async function subscribeToPush(userId: string) {
+  const registration = await navigator.serviceWorker.ready;
+  const subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_KEY!),
+  });
+  // Save subscription to backend
+  await fetch('/api/push/subscribe', {
+    method: 'POST',
+    body: JSON.stringify({ userId, subscription }),
+  });
+}
+```
+
+For the backend, use `web-push` (Node.js) or your platform's push service.
+
+---
+
+## Phase 7: Verify installability and offline  [LOW freedom — do not skip]
+
+Lighthouse removed its PWA category in v12.0 (April 2024), so there is no PWA
+score to target. Check in Chrome DevTools → Application instead: the
+**Manifest** pane's Installability section must list no errors, and in
+**Service workers** tick **Offline** and reload `start_url`.
+
+Key checks:
+- [ ] Manifest present and installable
+- [ ] Service worker registered
+- [ ] Works offline (offline page or cached response)
+- [ ] HTTPS (localhost counts)
+- [ ] `viewport` meta tag present
+- [ ] Icons correct size and format
+- [ ] `start_url` loads while offline
+
+---
+
+## Guardrails
+
+- **Service worker caching can break deployments** if old caches persist.
+  Use `registerType: 'autoUpdate'` (the new service worker takes control at once; open tabs reload only when the app registers through `virtual:pwa-register`, e.g. `registerSW({ immediate: true })`) or `'prompt'` (the user is asked to reload) — never a silent background update that keeps serving stale precached code.
+- **Never cache auth tokens or sensitive API responses** in the service worker.
+- **Test offline mode manually** via DevTools → Network → Offline before shipping.
+- **Capacitor apps**: confirm the Capacitor bridge still works after adding the
+  service worker by running `mobile-emulator-test`.

package/skills/enhance-readability/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: enhance-readability
+description: >
+  Audit and fix how easily content is understood: line length (CPL), reading
+  level, grouping, deadspace, icons or tables that cut verbosity. Use when
+  "hard to read", "too dense", "reading level", "cognitive load", or "turn
+  this prose into a table".
+license: MIT
+---
+
+> Surface router: `/uiux`. You are here: `enhance-readability`. Native iOS/Android (SwiftUI / Compose, no web layer) is out of scope — use Apple HIG / Material directly.
+
+# enhance-readability — Make content understood
+
+**Degree of freedom: MIXED.** Text-metric measurement `[LOW freedom — run exactly]`;
+grouping, iconography, and tone `[HIGH freedom]`.
+
+Audit-and-fix. The goal is **comprehension**: the least mental effort for the
+reader to understand the content. `enhance-web-ui` makes it look good;
+`audit-responsive` makes it fit the screen; this makes it *understood*.
+
+The backbone is **Cognitive Load Theory** (working memory is small — cut
+extraneous load) and **Gestalt** (the brain auto-groups visual elements —
+design with that). A consequence of CLT / information overload: showing
+*more* information can raise extraneous load and lower understanding. Replacing
+a dense paragraph with one table or diagram is a comprehension win **only when
+the visual reduces total load** versus the text it replaces — never decoration.
+
+## How to reason
+
+1. **Observe** — what makes this effortful? (dense text / no hierarchy / wall of prose / no whitespace / wrong register)
+2. **Diagnose** — which of the six channels, and which Gestalt / CLT principle
+3. **Classify load** — extraneous (bad presentation — always cut) vs intrinsic (inherent complexity — restructure / chunk) vs germane (productive — keep)
+4. **Lever** — cheapest channel that removes that load
+5. **Severity** — how much it blocks understanding on the primary path
+
+## Worked example
+
+> **Observe:** a pricing section is 3 dense paragraphs comparing 4 plans, 105 CPL, one grey block.
+> **Diagnose:** dim 4 (comparison is a table), dim 3 (no proximity grouping), dim 1 (CPL 105 > 80), dim 5 (no whitespace).
+> **Classify:** extraneous (prose form) + intrinsic (4-way comparison → chunk into a table).
+> **Lever:** generate a 4-column comparison table; cap surrounding text at 66ch; icon per tier.
+> **Handoff:** table collapse on mobile → `audit-responsive`; table tokens → `audit-uiux-design-system`.
+
+## Self-critique before reporting
+
+- **Load reduced** — each change names extraneous vs intrinsic; "looks cleaner" is not the test
+- **Right owner** — breakpoints → `audit-responsive`; personality → `enhance-web-ui`; WCAG floor → `audit-accessibility`; voice authenticity → `plan-antislop`; tokens → `audit-uiux-design-system`
+- **Language-correct** — CJK judged at 40 CPL (WCAG 2.2 SC 1.4.8)
+- **Visuals earn their place** — generated graphic reduces load vs the text it replaces
+- **Voice intact** — tone lowers effort without flattening the author
+
+## The six channels (one goal: lower cognitive load)
+
+1. **Text** — legibility and reading level (measurable).
+2. **Separation** — Gestalt figure-ground + similarity (weight / color / rule).
+3. **Layout** — proximity + chunking (~4 working-memory units) + hierarchy.
+4. **Iconography & graphics** — icons paired with text; generate a visual only if load drops.
+5. **Deadspace** — negative space that directs focus. "Is space aiding understanding," not "fix the 1440px grid."
+6. **Tone & accent** — register/rhythm for the audience. Authenticity / AI-tells → `plan-antislop`.
+
+Each is sized per form factor as *comprehension judgment*, not breakpoint CSS.
+
+## Boundary — what this skill does NOT own
+
+- **Breakpoint layout / matcher / CSS grid / "desktop = stretched phone"** → `audit-responsive`
+- **Visual personality, brand, aesthetic composition** → `enhance-web-ui`
+- **WCAG pass/fail contrast/size floor** → `audit-accessibility` (this skill treats the floor as the minimum)
+- **Voice authenticity / anti-slop** → `plan-antislop`
+- **Design-token / system coherence** → `audit-uiux-design-system`
+
+Note and hand off. Do not duplicate.
+
+## Text thresholds (Phase 1)  [LOW freedom — run exactly]
+
+House targets, measured not eyeballed. CPL/CJK and line-height come from
+[WCAG 2.2 SC 1.4.8 Visual Presentation](https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html)
+(AAA *mechanism* criterion; we use the numbers as authoring targets):
+
+- **CPL / measure**: 50–75, ~66 sweet spot; hard limit **80 Latin**, **40 CJK** (日本語).
+- **Line-height**: 1.5–1.8 body. **Font**: body ≥16px (16–18 optimal). **Paragraphs**: 2–4 lines.
+- **Contrast**: WCAG AA floor is the minimum, not the goal — flag pale secondary text.
+- **Alignment**: left-align *running text* (do not justify). Opposite of `audit-responsive`'s left-stacked-*layout* anti-pattern.
+- **Reading level**: Flesch-Kincaid ≤8 for general UI (plain-language house target, not WCAG); sentences <~20 words; front-load; chunk.
+
+## Phase 0 — Scope the content surfaces  [HIGH freedom]
+
+Identify where *understanding* is the job: article/doc bodies, comparisons,
+dashboards, onboarding, help/FAQ, dense forms, data-heavy views, empty/error
+copy. Note language(s) (CJK vs Latin) and the primary comprehension goal
+("decide between plans", "learn the concept", "complete the task").
+
+## Phase 1 — Measure text legibility  [LOW freedom — run exactly]
+
+Per surface, measure rendered values: CPL at real width, line-height, body/caption
+px, paragraph length, contrast, alignment, reading level. Record value-vs-threshold.
+
+## Phase 2 — Visual channels (2, 3, 5) against Gestalt  [HIGH freedom]
+
+- **Separation (2):** distinct types look distinct, or one undifferentiated stream?
+- **Grouping (3):** related close, unrelated apart? Chunked to working-memory size? Clear first-look target?
+- **Deadspace (5):** whitespace separates and focuses, or everything is crammed and left-stacked? (Use of space for comprehension — not the breakpoint grid.)
+
+## Phase 3 — Iconography & graphics (4)  [HIGH freedom]
+
+Where prose carries a load a visual would carry better, propose (and generate if
+the environment supports it) a comparison table, flow/step diagram, scan-anchor
+icons, or a chart. Test: does it *reduce* total load vs the text it replaces?
+If not, do not add it. Existing icons: paired with text and consistent, or noise?
+(NN/g: almost no icon is universal without a label.)
+
+## Phase 4 — Tone (6), then fix in the system  [HIGH freedom]
+
+Register right for audience and goal (short + direct for tasks; warmer for
+onboarding). Preserve author voice. Fixes use the repo's design tokens and type
+scale — never one-off values; systemic gaps → `audit-uiux-design-system`.
+Generated visuals follow the design system. Keep diffs to comprehension.
+
+## Definition of Done
+
+- [ ] Surfaces scoped with per-surface comprehension goal; language(s) noted
+- [ ] Text measured value-vs-threshold (CPL incl. CJK, line-height, px, paragraph, contrast, align, reading level)
+- [ ] Separation, grouping, and deadspace assessed against Gestalt / CLT
+- [ ] Iconography/graphics assessed; visuals generated only if load drops
+- [ ] Tone assessed; author voice preserved
+- [ ] Findings classified by channel + load type + severity
+- [ ] Fixes use tokens/scale; systemic gaps flagged
+- [ ] Boundary respected (responsive / web-ui / a11y / antislop / design-system)
+- [ ] Self-critique applied; every change names the load it removes
+
+## Output format
+
+1. **Text measurement table** — surface | CPL | line-height | px | paragraph | contrast | align | reading level | vs threshold
+2. **Channel findings** — surface | channel (1–6) | Gestalt/CLT principle | load type | severity | fix
+3. **Proposed/generated visuals** — load-reduction rationale
+4. **Fixes applied** — token CSS + regrouping + visuals + copy/tone, before/after
+5. **Handoffs** — breakpoints / personality / WCAG / voice / tokens
+
+## Related
+
+- `enhance-web-ui` — looks good (composition / personality)
+- `audit-responsive` — container reflow per breakpoint
+- `audit-accessibility` — WCAG pass/fail floor
+- `plan-antislop` — voice authenticity / AI tells
+- `audit-uiux-design-system` — tokens / component SSOT
+- `enhance-web-ux` — flows / IA / information density of the *task*, not reading measure