/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.

---

Called by `/flagrare:ui-review`

When the arguments start with `called by /flagrare:ui-review`, the caller owns the session and the deliverable. Everything else in this skill still applies, coverage discipline included, with four changes:

• **Skip the `/goal` in Step 1.** ui-review already set one goal for the whole chain, and a second would silently replace it. Still create the Todo list.
• **Scope is the one target in the arguments** (a screen, a dialog, a flow, or a URL). For a URL with no source to enumerate, the scope is that URL plus every state reachable from its affordances without leaving the target.
• **Write to the folder the arguments name** (default `.ui-review/`) instead of `.ux-audit/`, and capture the extra states the arguments list (hover, focus, pressed, loading, reduced motion) plus the interaction inventory, in the same tab, numbered with the rest.
• **Skip Step 7's hand-off message.** Return the findings table, the coverage list, the interaction inventory and the screenshot paths; the caller merges them into its own report.

---

Step 1: Lock the goal explicitly

**Hard requirement.** Before any other tool call, you MUST call `/goal` yourself (unless called by `/flagrare:ui-review`, see above). 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-