--- name: audit-ux-journeys description: >- Cross-page UX audit for user stories, task completion, and information architecture — the layer audit-ux (per-page heuristics) doesn't cover. Derives real user stories from routes/nav/CTAs (not invented personas), scopes depth by audit trigger (KPIs dropping / complaints / redesign / pre-launch), audits IA structurally (click depth, orphan pages, dead ends, label consistency, grouping vs mental model, findability/first-click), then walks every core story end-to-end in a headed browser producing a task-completion matrix with friction logs. Evidence-disciplined: validates with analytics/funnels/drop-offs when available, otherwise marks findings as expert-judgment hypotheses — never presents taste as data. Reports impact×effort quick-wins vs roadmap. Use when "audit user flows", "user story audit", "information architecture / IA audit", "can users find X", "users get lost", "navigation audit", "funnel drop-off", "task completion", or "audit-ux-journeys". Per-page heuristics/microcopy stay with audit-ux. license: MIT --- # audit-ux-journeys — User-Story, Task-Completion & IA Audit A site can pass every per-page heuristic and still fail its users: every page individually clean, yet nobody can *find* the feature, the checkout takes nine steps with two dead ends, and the nav is organized by the database schema instead of the user's mental model. `audit-ux` judges **pages**; this skill judges **paths and structure** — whether real user stories can actually be completed, and whether the information architecture makes the product findable. The 2026 practitioner consensus is consistent: a UX audit is **not a list of personal opinions** — it derives from user goals, walks the actual journeys, audits navigation/IA against mental models, and grounds findings in behavioral evidence (funnels, drop-offs, session behavior) wherever data exists. When no data exists (pre-launch), the correct method is qualitative walkthroughs, *labeled as assumptions* — not silence, and not fake certainty. **Before ANY browser interaction, read `protocol-browser-anti-stall` and apply its rules to every step.** > **Report-first.** This skill produces a prioritized audit, then delegates fixes: per-page > heuristics/microcopy → **`audit-ux`** · single-screen improvements → **`enhance-web-ux`** · > forms → **`enhance-web-forms`** · WCAG → **`audit-accessibility`** · speed → **`audit-performance`** > · feature parity → **`audit-realworld`**. It owns the *cross-page journey and IA* layer and links > out rather than duplicating. --- ## Core principle — stories over pages, data over taste - **The unit of audit is a story, not a screen.** Every finding attaches to a user story ("As a returning customer, I want to reorder in under a minute") and a step in its path. - **Derive stories from the product, not from imagination.** Routes, nav, CTAs, README, marketing copy, and existing PRDs define what the product *claims* users can do. Audit those claims. - **Evidence or hypothesis — say which.** Every finding is tagged `[data]` (analytics/funnel), `[observed]` (reproduced in the walkthrough), or `[judgment]` (expert assumption to validate). Presenting `[judgment]` as `[data]` is the cardinal sin of UX audits. - **Findable beats beautiful.** A feature users can't reach doesn't exist. Depth, labels, and grouping are audited against the *user's* mental model, not the code's module layout. - **Prioritize by impact × effort.** A slow checkout matters more than a slow About page. Quick wins ship first; low-impact issues are deprioritized regardless of how easy they are. --- ## Phase 0 — Derive the stories and scope the trigger ### 0a. Extract user stories from the real product ```bash # Route inventory (framework-appropriate) fd -H 'page\.(tsx|jsx|vue|svelte)' app/ src/app/ 2>/dev/null; fd -H . src/routes pages 2>/dev/null -t f # Navigation + entry points rg -n -i "/dev/null ``` Write 5–10 stories max, each with a **completion signal**: `As [persona], I want [goal] — done when [observable outcome]`. If `design-prd` output or `plan-test-coverage` story inventory exists, start from it (same stories, different lens). ### 0b. Scope by audit trigger (sets depth and method) | Trigger | Method emphasis | |---|---| | **KPIs dropping** | Targeted: the affected funnel only; cross-validate with data; check recent changes | | **Complaints rising** | Thematic: cluster complaints → walk those stories first; treat complaints as hypotheses | | **Redesign planned** | Comprehensive: all stories + full IA; findings shape the redesign | | **Pre-launch / no data** | Qualitative walkthroughs of critical flows (signup, onboarding, checkout); **label all findings `[judgment]`** | | **"Just optimize"** | Holistic roadmap: start at highest-impact stories, surface UX debt | --- ## Phase 1 — Information architecture & navigation audit (structural) Build the route tree, then audit structure against findability. Detailed commands and pass/fail signals in [references/checklist.md](references/checklist.md). | # | Check | Red flag | |---|---|---| | IA1 | **Click depth per story target** — core-story destinations reachable in ≤3 clicks from landing | Money pages buried 4+ clicks deep | | IA2 | **Orphan pages** — every route reachable from some nav/link path | Routes with zero inbound links (exist only by URL) | | IA3 | **Dead ends** — every page offers a forward action | Pages with no CTA/next step (journey stalls) | | IA4 | **Label consistency** — nav label ≈ page title ≈ H1; same concept = same word everywhere | "Billing" in nav → "Payments" title → "Invoices" H1 | | IA5 | **Grouping vs mental model** — nav organized by user tasks/goals | Organized by DB schema or team org chart | | IA6 | **First-click logic** — for each story, the correct first click from the landing page is the *obvious* one | Correct path requires insider knowledge | | IA7 | **Wayfinding** — breadcrumbs in hierarchies ≥3 deep; current location highlighted | User can't answer "where am I?" | | IA8 | **Search & filtering** — present and functional for large content/data sets | 200 items, no search; filter resets on nav | | IA9 | **URL sanity** — URLs human-readable, hierarchical, shareable | Opaque ids everywhere; state lost on refresh | Verdicts: `Pass / Fail / N-A` with `file:line` or route evidence. IA6 requires the browser (Phase 2). ## Phase 2 — Story-by-story task walkthroughs (headed browser) Walk **every** story from Phase 0, entry → completion signal, desktop **and** mobile viewport (390px — most real friction is mobile). Per story record: ``` STORY: [As … I want … — done when …] Trigger tag: [data|observed|judgment] Entry: [landing/deep-link] Steps to goal: N clicks / M inputs Friction log: [each hesitation, mislabel, backtrack, surprise — with screenshot] Error recovery: [wrong input / back button / refresh mid-flow — data survives? path recoverable?] Success moment: [is completion confirmed clearly? what happens next?] Result: COMPLETED / COMPLETED-WITH-FRICTION / BLOCKED (blocker = finding, severity Blocker) ``` Rules: screenshots to `.playwright-mcp/` per the artifact-hygiene rule; forms judged only for flow-level friction (field-level → `enhance-web-forms`); per-page heuristic violations noticed along the way are *handed to* `audit-ux`, not re-audited here. ## Phase 3 — Evidence layer (validate or label) ```bash # What analytics exist? rg -n -i "gtag|googletagmanager|G-[A-Z0-9]{6,}|posthog|clarity\.ms|hotjar|amplitude|mixpanel|plausible|umami|fathom" -g '*.{ts,tsx,js,jsx,html,vue,svelte}' -l ``` - **Data available** (GA4/PostHog/Clarity/Amplitude/Mixpanel, or Sentry for error hotspots): pull funnel completion and drop-off per story path, top exit pages, rage-click/dead-click signals. Upgrade or *refute* walkthrough findings — a "confusing" page with a 95% pass-through rate is not a Critical finding. - **No data** (typical pre-launch): every finding stays `[observed]` or `[judgment]`. Say so explicitly in the report, and recommend minimal instrumentation (page + funnel events on core stories) as its own roadmap item so the *next* audit has evidence. ## Phase 4 — Prioritized report ```markdown ## UX Journey & IA Audit — [product] — [date] **Trigger:** [scenario] · **Stories audited:** N · **Evidence:** [analytics available? which] **Working well:** [1–3 genuine strengths — always present] ### Task-completion matrix | Story | Result | Steps | Frictions | Blockers | Evidence | |---|---|---|---|---|---| | Reorder as returning customer | COMPLETED-WITH-FRICTION | 7 (target ≤4) | 3 | – | [observed] | | Find pricing from landing | BLOCKED (mobile) | – | – | menu unreachable | [observed] | ### IA verdicts (IA1–IA9) | Check | Verdict | Evidence | |---|---|---| ### Findings (each: severity · evidence tag · story · impact×effort quadrant) | # | Finding | Severity | Evidence | Story/step | Impact | Effort | Fix via | |---|---|---|---|---|---|---|---| | 1 | Checkout loses cart on refresh at step 3 | Blocker | observed | buy §5 | High | Med | debug-error → enhance-web-ux | ### Quick wins (high impact · low effort — do first) ### Roadmap (high impact · high effort) ### Deprioritized (low impact — listed, not scheduled) ### Validate next (all [judgment] findings + the instrumentation to settle them) ``` Language discipline: neutral, behavior-grounded observations ("3 of 5 walkthrough runs backtracked at X"), never accusatory ("this design is bad"). One observation per finding, one paragraph max. **Forbidden:** presenting `[judgment]` as data; re-auditing per-page heuristics/microcopy that `audit-ux` owns; inventing personas unmoored from the product; recommending a full redesign when incremental fixes close the findings; a findings dump with no impact×effort prioritization; only-negatives reports (name what works); auditing without walking the stories (a route-tree grep alone is not a journey audit). --- ## Related - `audit-ux` — per-page NN/g heuristics, Laws of UX, microcopy, emotional design (the page lens to this skill's path lens) - `enhance-web-ux` / `enhance-web-forms` — fix the screens and forms this audit flags - `audit-uiux-design-system` — visual token/component compliance - `audit-accessibility` / `audit-performance` — WCAG and speed lenses (delegated) - `audit-realworld` — full-stack feature parity vs the RealWorld reference - `plan-test-coverage` — same story inventory, test-coverage lens; share Phase 0 output - `design-prd` — where stories come from on greenfield; this skill audits them post-build - `test-playwright` — turn walkthroughs into regression coverage after fixes - `complete-everything` — close the audited gaps to done with verification