Skip to content

jezweb/claude-skills / plugins/dev-tools/skills/ux-audit

ux-audit

Verified

Walk through a live web app AS a real user to find usability + behavioural bugs that static reviews miss. REQUIRES proof of interaction (typing, clicking, sending, observing) before any verdict — a sweep that didn't interact terminates with verdict 'Incomplete'. Walks threads, exercises every element, runs the multi-pane stress matrix, visual polish sweep, component perfection checklist, automated a11y (axe-core), pragmatic performance budget (LCP/CLS/INP), scenario battery (11 scenarios), and stress recipes including the real-flavour data battery. Hard gates: console errors/warnings = 0, network 5xx = 0, layout collapse = 0, axe Critical/Serious = 0, perf budget green. Audit-the-audit meta-check rejects rushed reports. Each finding has reproduction steps, evidence path, and suspected code location. Trigger with 'ux audit', 'walkthrough', 'qa sweep', 'audit the app', 'dogfood this', 'check all pages', 'find what's broken', 'stress the UI'.

references/interaction-manifest.md

View on GitHub
# Interaction Manifest

The Interaction Manifest is the proof that the walkthrough actually walked. Without it, the audit cannot produce a verdict — the only legal output is **Incomplete**.

This file specifies what counts as a complete manifest, the template, the replay protocol when a manifest entry doesn't match expected behaviour, and worked examples.

## Why this exists

The previous version of ux-audit had a "Walkthrough" mode but didn't enforce it. In practice, agents drifted to sweep mode — query the DOM, read text, move on — because it's faster and feels productive. That mode is blind to behavioural bugs by definition.

The 2026-04-29 vite-flare-starter audit failure proved the cost: six catastrophic bugs went live (Send button doesn't clear input, @-mention doubles the handle, vertical-text-stacking in spaces, etc.) while the audit said "no Critical issues". Every one of those bugs only surfaces under interaction.

The manifest closes that gap. It's a non-negotiable proof requirement. Skipping it means the audit terminates with `Incomplete`.

## What counts as "complete"

A manifest is complete when, for every page audited, all six required entry types are logged with proof:

| Required entry | What it looks like | Proof artefact |
|---|---|---|
| **Type into ≥ 1 input** | Real text, not just clicked | `textarea.value` after typing, screenshot |
| **Trigger ≥ 1 primary action** | Send / Save / Submit / Create / Publish | Network request fired, screenshot before + after |
| **Open ≥ 1 modal or detail pane** | Click a row, open a thread, open a settings panel | Screenshot of opened state |
| **Console read after primary action** | `read_console_messages` call | Output captured (0 warnings or list of warnings) |
| **Screenshot before AND after primary action** | Two screenshots, ideally same viewport | Files written, paths logged |
| **Verify expected post-action state** | Input cleared, success toast, route change, list updated | Assertion logged with selector + expected value |

Six types per page, one row per check. Multi-pane stress adds more entries; scenarios add more entries. The minimum is six per audited route.

## Manifest template

```
INTERACTION MANIFEST — /dashboard/spaces/marketing-pod
  Persona: SME owner, time-pressed, low tech comfort
  Viewport: 1280×800 (desktop default for this persona)
  Panes open: sidebar, members, thread

  [✓] 14:32:01  TYPE     Typed "@assistant test" into message input
                         Selector: textarea[placeholder*="message"]
                         Result: textarea.value === "@assistant test"

  [✓] 14:32:03  PICK     Picked @assistant from autocomplete
                         Selector: li[data-mention-id="assistant"]
                         Screenshot: .jez/audit-evidence/spaces-after-pick.png

  [✓] 14:32:05  SUBMIT   Clicked Send
                         Selector: button[aria-label="Send"]
                         Screenshot before: .jez/audit-evidence/spaces-before-send.png
                         Screenshot after: .jez/audit-evidence/spaces-after-send.png
                         Network: POST /api/messages → 200 (87ms)

  [✓] 14:32:06  ASSERT   Verified input cleared within 1000ms
                         Assertion: textarea.value === ""
                         Result: PASSED (cleared in 142ms)

  [✓] 14:32:08  ASSERT   Verified message appeared in transcript
                         Assertion: [data-message-id] count increased by 1
                         Result: PASSED (count: 12 → 13)

  [✓] 14:32:12  OPEN     Opened thread on the new message
                         Selector: [data-message-id="msg-13"] [data-thread-trigger]
                         Screenshot: .jez/audit-evidence/spaces-thread-open.png

  [✓] 14:32:13  ASSERT   Verified main column width ≥ 200px after thread open
                         Assertion: main.getBoundingClientRect().width >= 200
                         Result: FAILED (width: 184px) ← FINDING H-2

  [✓] 14:32:14  CONSOLE  Read after thread open
                         Errors: 0
                         Warnings: 1 ← FINDING H-1
                         Warning: "VoiceClient: protocol mismatch (1.2 vs 1.4)"

  [✓] Network requests inventoried for the page session
        5xx: 0     403/404 (auth pages): 0     Total: 8

  ─────────────────────────────────────────────────────────────────
  Required entries: 6 / 6 ✓
  Findings produced from this manifest: 2 (H-1 console, H-2 layout)
```

## Required entry types in detail

### TYPE
- Real text into an input. Not just a click on the input.
- For password fields, type a fake password (something like `audit-test-123!`).
- For email fields, type a valid-format fake address.
- For search inputs, type something likely to match (or `zzzzz` to trigger empty state).
- Verify the input received the text (`getByRole('textbox').toHaveValue(...)`).

### PICK
- Optional but common: dropdown selection, autocomplete pick, file upload, date picker, mention picker.
- Required if the page has any picker/combobox/autocomplete that's part of the primary flow.
- Verify the picked value is reflected in the form / display.

### SUBMIT
- The primary action: Send, Save, Submit, Create, Publish, Pay, Share, Send invitation.
- Click it. Watch the network, watch the DOM.
- Capture screenshot before AND after.
- Capture the network request: URL, method, status code, latency.

### OPEN
- Click into a row, open a modal, open a detail pane, open a thread, open a settings panel.
- Captures the "what happens after this lands" view.
- Required because most layout / pane interaction bugs are only visible after opening.

### ASSERT
- Each ASSERT is a yes/no check on observed state.
- Common assertions:
  - Input cleared after submit
  - Success toast appeared (`.toast`, `[role="status"]`, etc.)
  - Route changed (URL pathname check)
  - List item count increased / decreased
  - Loading spinner appeared during action
  - Loading spinner disappeared after action
  - Error toast appeared on invalid input
  - Pane width ≥ minimum (200px is a common floor)
- Failed assertions become findings.

### CONSOLE
- After every SUBMIT (and ideally every state change), read the console.
- Tool: `mcp__claude-in-chrome__read_console_messages` or Playwright `page.on('console', ...)`.
- Any warning or error becomes a finding (Hard Gate).

### NETWORK
- Inventory at the end of each page session.
- Status code distribution: 2xx, 3xx, 4xx, 5xx counts.
- Any 5xx = Critical. Any 403/404 on an authenticated page = High.

## Replay protocol — what to do when an assertion fails

When an ASSERT fails, the finding workflow:

1. **Don't move on.** That's a behavioural bug surfacing right now.
2. **Capture the failure state**: screenshot, DOM at the failure point, network log, console.
3. **Repeat the action** — does the bug reproduce? If yes, it's stable. If no, capture the variation.
4. **Vary one input**: type different text, click in different order, change viewport. Does the bug always happen, or only with specific input?
5. **Check the underlying code** if accessible — `Read` the relevant file, identify the suspected location.
6. **Write the finding** with full reproduction steps, evidence path, suspected location, suggested fix.
7. **Continue the manifest** with the rest of the required entries — don't skip them just because one failed.

A page can have multiple findings; the manifest captures all of them in order.

## Example manifest entries for common page types

### List page (clients, projects, messages)
- TYPE into search
- ASSERT search filters the list
- OPEN one item (click row)
- ASSERT detail pane / detail page loaded
- CONSOLE read

### Form page (settings, create new X)
- TYPE into every required field with realistic data
- TYPE into one optional field
- PICK any required dropdown
- SUBMIT (Save / Create)
- ASSERT success toast OR error toast appeared
- ASSERT route changed (or stayed, depending on intent)
- CONSOLE read

### Conversation / thread page
- TYPE a message
- SUBMIT (Send)
- ASSERT input cleared
- ASSERT message appeared in transcript
- OPEN thread on message
- ASSERT thread pane opened, main column width ≥ 200px (multi-pane stress!)
- CONSOLE read

### Dashboard (multi-widget)
- For each widget: read content, screenshot, OPEN any drill-down
- TYPE into any inline filter / search
- CONSOLE read after each interaction (dashboards are notorious for racy data fetches)

## Interaction Manifest as a coverage metric

At the end of the audit, publish:

```
INTERACTION COVERAGE
  Pages audited: 14
  Required entries logged: 84 / 84
  Pages with complete manifest: 14 / 14
  Pages with incomplete manifest: 0
```

If any page has < 6 required entries, that page is `Incomplete` and the overall verdict is `Incomplete` — even if every observed interaction passed.

## Anti-patterns

Things that look like manifest entries but aren't:

- "Read the page text" — not an interaction. Doesn't count.
- "Hovered over the menu" — counts as a state change but doesn't satisfy SUBMIT requirement.
- "Clicked the menu open" — only counts if the menu IS the primary action; otherwise it's an OPEN.
- "Took a screenshot" — supporting evidence, not an entry on its own.
- "Read the source code" — useful for finding suspected location but doesn't replace interaction.

If your manifest is full of `READ`, `INSPECT`, `QUERY`, you've drifted to sweep mode. Stop, restart with TYPE.

## How this maps to the verdict

| Manifest state | Allowed verdicts |
|----------------|------------------|
| Complete (≥ 6 entries per page, all phases run) | Pass / Conditional Pass / Fail |
| Incomplete on any page | Incomplete (cannot upgrade to Pass) |
| Console hard gate breached | Fail (cannot be Pass / Conditional) |
| Network 5xx hard gate breached | Fail (Critical) |

Hard gates auto-fail. Incomplete manifest auto-blocks Pass. Together they make "audit said clean while bugs were live" structurally difficult.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall