| 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
fd -H 'page\.(tsx|jsx|vue|svelte)' app/ src/app/ 2>/dev/null; fd -H . src/routes pages 2>/dev/null -t f
rg -n -i "<nav|navbar|sidebar|menu|Link.*href|routerLink|to=\"/" -g '*.{tsx,jsx,vue,svelte}' -l
rg -n -i "get started|sign up|buy|checkout|create|upload|invite|export|book|order|subscribe" -g '*.{tsx,jsx,vue,svelte,md}'
fd -H -i 'prd|user-stor|journey|persona' docs/ .cursor/ 2>/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.
| # | 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)
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
## 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 flagsaudit-uiux-design-system — visual token/component complianceaudit-accessibility / audit-performance — WCAG and speed lenses (delegated)audit-realworld — full-stack feature parity vs the RealWorld referenceplan-test-coverage — same story inventory, test-coverage lens; share Phase 0 outputdesign-prd — where stories come from on greenfield; this skill audits them post-buildtest-playwright — turn walkthroughs into regression coverage after fixescomplete-everything — close the audited gaps to done with verification
