/ux-audit

name: ux-audit
description: "Goal-locked UX audit. Drives a real browser through every reachable route (or a user-specified scope) and every visible affordance, screenshots each state, and ships a severity-ranked findings table (High/Medium/Low) with location, why-it's-painful, and recommended fix. Installs Chrome DevTools MCP automatically if missing. Pretends to be a first-time user, surfaces jargon, mystery glyphs, dead-ends, choice paralysis, color-only signals, jarring tone, broken empty states. Use when the user says 'UX audit', 'test all paths', 'click through everything', 'pretend to be a user', 'find painful flows', 'find UX issues', 'usability pass', 'walk through the app', or after a feature lands and before a release. Triggers even if 'audit' isn't in the request, any phrasing about exhaustively trying the app from a user's perspective qualifies."

UX Audit

A goal-driven walkthrough of the running app from a first-time user's perspective. The pass ends only when every reachable route has been visited, every visible affordance on those routes has been exercised, and every observation has been logged with a severity, a location, a reason, and a recommended fix.

This is **not** a smoke test (which validates a single feature against acceptance criteria) and **not** an accessibility audit (which has its own tooling). This skill answers a different question: *if a real human picked up this app cold and tried to use it, where would they stumble, hesitate, get confused, or feel patronized?*

The persona matters. Drop the engineer-with-context lens; adopt the new-user lens. A button labelled `Set Your Light` is not "clear because the team decided", it is jargon to the new user. Record it as jargon.

---

Why this exists

Teams ship features they can no longer see. Designers, PMs, and engineers all develop blindness to their own product, they know which button does what, so they stop noticing that the button is mislabelled, that the empty state is hostile, that the "Ash" mode is a void, that the modal traps the user, that the toast says "this project has been quiet for weeks" about a project the user created twelve seconds ago. Static checks don't catch these. Unit tests don't catch these. PRs don't catch these. A human cold-walking the app catches them, but humans are expensive and forget what they noticed five minutes later.

This skill is the cheap, consistent, written-down version of that walk. The output is a markdown artifact (not a slide deck, not a JIRA dump) that the team can read, prioritise, and act on the same day.

---

Step 1: Lock the goal explicitly

**Hard requirement.** Before any other tool call, you MUST call `/goal` yourself. This is not a suggestion to the user. You, the executing model, must invoke the goal tool directly. Without it, context compaction and turn limits will cause early termination -- the audit visits 15-40 routes and the model will quit by route 5 without a durable goal holding it in place.

Determine scope

The user may specify a scope when invoking the skill:

• **No scope given** (e.g. "run a UX audit") -- scope is ALL routes. The goal text says "every reachable route."
• **Scope given** (e.g. "UX audit the onboarding flow", "audit /settings and /profile") -- scope is only the routes/flows specified. The goal text names those routes explicitly.

Call `/goal` with text adapted to the scope:

**Full scope (default):** > Drive the running app from a first-time user's perspective. Exhaust every reachable route and every visible affordance on those routes. Produce a severity-ranked findings table in `.ux-audit/FINDINGS.md` along with numbered screenshots. Do not stop until coverage is complete.

**Scoped:** > Drive the running app from a first-time user's perspective. Exhaust every route and affordance within: [user's specified scope]. Produce a severity-ranked findings table in `.ux-audit/FINDINGS.md` along with numbered screenshots. Do not stop until coverage of the specified scope is complete.

After setting the goal, also create a Todo list (one item per route within scope, populated in Step 2). The Todo list tracks coverage; the goal prevents the harness from letting you stop. Both are required. Neither is optional.

Prerequisites -- do not skip, do not degrade, do not ask permission

1. **Chrome DevTools MCP must be available.** This skill requires `take_screenshot`, `take_snapshot`, `navigate_page`, and `click`/`fill` from Chrome DevTools MCP. If the tools are not available in this session, **fix it yourself without blocking**. Be fully autonomous -- do not stop and wait for the user at any point in this checklist.

**A. Is the chrome-devtools-mcp plugin installed?**

• Check: look for `chrome-devtools-mcp:chrome-devtools` in the available skills list
• If missing: install it. Try in order: `npm i -g chrome-devtools-mcp@latest` (disable sandbox) → `npm i -g chrome-devtools-mcp@latest --prefix ~/.local` (if EACCES) → `pnpm add -g chrome-devtools-mcp@latest`

**B. Is Chrome running with remote debugging?**

• Launch Chrome yourself. Run this command (disable sandbox):
• macOS: `open -a "Google Chrome" --args --remote-debugging-port=9222`
• Linux: `google-chrome --remote-debugging-port=9222 &`
• If Chrome is already running without the flag, kill it first: `pkill -f "Google Chrome"` (macOS) or `pkill chrome` (Linux), wait 2 seconds, then launch with the flag.
• Do NOT ask the user to do this. Do it yourself. You CAN launch Chrome from a bash command.

**C. Are the MCP tools appearing?**

• After launching Chrome, invoke the `chrome-devtools-mcp:chrome-devtools-cli` skill if available, or run `chrome-devtools status` to verify connection.
• If tools still don't appear in your deferred tools list after Chrome is running, tell the user: "Run `/reload-plugins` -- Chrome is now running with debugging, but Claude Code needs to reconnect its MCP server." This is the ONE thing that may requi