jezweb/claude-skills / plugins/dev-tools/skills/ux-audit
ux-audit
VerifiedWalk 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |