ux-audit

What this skill does

# UX Audit

Walk through a live web app AS a real user. The audit is **interaction-first** — typing, clicking, sending, watching, screenshotting. A static DOM sweep cannot produce a verdict.

## Verdict states

The audit ends in exactly one of:

- **Pass** — Critical = 0, High = 0, all hard gates green, Interaction Manifest complete.
- **Conditional Pass** — Critical = 0, High = 0, all hard gates green, but Medium/Low present.
- **Fail** — at least one Critical or High finding, OR a hard gate red.
- **Incomplete** — Interaction Manifest missing required entries, a phase wasn't run, OR the audit-the-audit meta-check fires (manifest timestamps clustered < 0.5s apart, screenshots fewer than 2 × routes, console reads fewer than 1 × routes, Phase 3 took < 1m for an exhaustive audit). Not legal to upgrade to Pass even if everything observed looked fine.

If the work doesn't include a complete Interaction Manifest, the only legal verdict is **Incomplete**. "It looked OK" is not Pass. A clean Pass with implausible timings is rejected — the agent must redo the audit with real interaction.

## Hard gates

These auto-fail the audit. They cannot be downgraded.

| Gate | Threshold | Severity if violated |
|------|-----------|----------------------|
| Console errors during walkthrough | > 0 | Critical |
| Console warnings during walkthrough | > 0 | High |
| Network 5xx | > 0 | Critical |
| Network 403 / 404 on authenticated pages | > 0 | High |
| Layout collapse at any tested viewport / pane combo | > 0 | High |
| axe-core Critical violations on any audited page | > 0 | Critical |
| axe-core Serious violations on any audited page | > 0 | High |
| LCP on representative route (pragmatic budget) | > 4.0s | High |
| CLS on representative route | > 0.25 | High |
| INP on representative route | > 500ms | High |
| Required Interaction Manifest entry missing | n/a | Incomplete |
| Manifest median gap between entries < 0.5s | n/a | Incomplete (didn't actually interact) |

A console warning is High *minimum*. A 5xx is Critical *automatically*. There is no "Medium console error" — that category does not exist in this skill.

axe-core thresholds are run **per page** (>1 violation on any single page fails). Performance thresholds are run **once on a representative route** (per-page is overkill); pragmatic budget is well above broken, well below CWV-strict. Full thresholds + rationale in [references/performance-budget.md](references/performance-budget.md). Full a11y wiring + severity mapping in [references/a11y-automation.md](references/a11y-automation.md).

### Allowlist for known noise

Some apps have known-noisy console / network categories that aren't bugs (Sentry info logs, browser-extension chatter, expected 401 on auth-check probes). Read the audit-config file before Phase 3 and apply its allowlist. Path fallback: `.jez/audit-config.yml` → `audit-config.yml` → `.audit/config.yml`. Allowlisted entries stay in the Interaction Manifest but suppress from findings. Verdict block shows both raw and allowlisted: `Console warnings: 3 (1 allowlisted, 2 reportable)`.

Default without a config: every console error / warning is a finding. Format, semantics, surface overrides in [references/audit-config.md](references/audit-config.md).

## Phases (in order)

1. **Pre-flight** — Persona Lock, browser tool, URL, viewport, capability tests
2. **Discovery** — sitemap, thread inventory, element inventory
3. **Walkthrough** — Interaction Manifest, threads, element exhaustion, multi-pane stress, first-time-user lens, live interaction smoke
4. **Polish** — visual polish sweep, component perfection checklist
5. **Stress** — scenario battery (11 scenarios) + extended stress recipes
6. **Verdict** — verdict state, hard-gate scorecard, perfection roadmap, findings with reproduction
7. **Fix-and-verify** — patch findings, re-walk affected slices, update report

For a 30-second pre-deploy check, use the dogfood drill at the bottom of this file — a project-level rule, not a skill invocation.

## Phase 1 — Pre-flight

Five gates. Stop if any fail.

### 1. Persona Lock

The audit needs a persona before anything else. Without a locked persona, findings drift toward generic "looks fine".

Source the persona in this order:

1. **Argument** — if the user provided one ("ux audit as a busy insurance broker")
2. **Project personas** — read existing persona files (fallback chain: `.jez/audit-personas/<slug>.md` → `docs/personas/<slug>.md` → `personas/<slug>.md` → `.audit/personas/<slug>.md`). The first match wins.
3. **Ask once** — *"Who uses this app and what are they trying to get done?"*

Capture: role, tech comfort, time pressure, emotional state, device context. A good persona predicts what they'd miss ("A receptionist between phone calls won't scroll below the fold").

Lock the persona by writing the chosen persona at the top of the audit report. Every finding must be defensible from this persona's perspective. If you catch yourself thinking *"a developer would know..."* — stop. Your persona doesn't.

**Always also run the first-time-user lens** (mandatory, see Phase 3) on every multi-page feature, even when the explicit persona is something else. It's the single biggest blind spot for AI / internal tooling.

See [references/persona-lock.md](references/persona-lock.md) for the persona library and writing protocol.

### 2. Browser tool

| Target | Tool | Why |
|--------|------|-----|
| **Authenticated app** | Chrome MCP | Uses your real logged-in Chrome session — OAuth, cookies, RBAC just work |
| **Public site** | Playwright MCP | No login needed |
| **Neither available** | **Stop** | Ask the user to connect Chrome MCP or install Playwright |

Do **not** silently fall back to a fresh Playwright session for an authenticated app — the audit is worthless if you can't log in. If Chrome MCP isn't connected, stop and say: *"Open Chrome, click Connect in the Claude extension, then rerun."*

See [references/browser-tools.md](references/browser-tools.md) for commands.

### 3. URL

Prefer the deployed/live version — real auth, real latency, real CDN and CORS. Discovery: read project CLAUDE.md / README for "URL" → check stack config (`wrangler.jsonc`, `vite.config.ts`, `next.config.js`, `config/database.yml`, `manage.py`, `.env` `APP_URL`, `wp-config.php`) → `lsof -i :PORT` (common: 5173 Vite, 3000 Next/Rails, 8000 Django/Laravel, 8787 Wrangler, 4321 Astro) → ask. Stack-specific guide in [references/project-adaptation.md](references/project-adaptation.md). Use local only if the user asks or the feature isn't deployed.

### 4. Viewport

Pin the window at 1440×900 to start. Phase 3 multi-pane stress tests 375 / 768 / 1024 / 1280 / 1440 / 1920. **Do not go above 2000px** — it breaks the harness.

### 5. Capability tests

Before any walkthrough, prove the tools work — one call each:

- One screenshot
- One console read
- One network request inventory
- One element selector query

If any fail, stop and fix the connection before starting the audit. An audit blind to console output is worthless.

## Phase 2 — Discovery

### Sitemap crawl

Build the complete page inventory before auditing any page.

1. **Router config** — read the app's route definitions (React Router, TanStack Router, Next.js app dir)
2. **Nav crawl** — click through every section and sub-section of the sidebar/menu
3. **Deep links** — URLs in CLAUDE.md, docs, or a prior audit report

One line per route, with purpose: `/app/clients — list of clients, search, add new`.

### Thread inventory

Identify 3–5 real tasks that make up a user's day. These are the spines of the audit.

How to find them: ask the user, read CLAUDE.md / README, infer from top-level nav. Examples: insurance broker → renew a policy, create a client, work today's queue. Project management → morning triage, update a task, send a client summary. Spaces / chat app → create a space, send a message, open a thread.

### Element inventory

For each route as you reach it, list every interac