Part of super-ux — see system-map.md for the whole pipeline and the four sync rules. Start any audit by running the linter (

python3 docs/ux/lint.py

) — it catches structural drift for free before the code-tracing passes.

docs/ux/scenarios.md

docs/ux/audits/

docs/ux/scenarios.md

ux-scenarios

docs/ux/foundation.md

docs/ux/flows.md

quick

standard

deep

1. Scenario pass — the loop below: code vs every scoped scenario.
2. Flow & screen conformance — code vs flow diagrams (every node reachable, every edge incl. error edges wired) AND code vs

   screens.md

   (every registered screen's states rendered, elements present,

   Coverage

   accurate). A screen whose code diverges from its record →

   drifted

   finding; flip its Status to

   drifted

   . When Figma is enabled, check each state has a frame link and flag empty/obviously-stale links (a link the registry marks but the design lost); with the Figma MCP connected,

   get_metadata

   confirms the frame still exists under its expected

   SCR-NN/<Screen>/<state>

   name without pulling full design context. A screen carrying a

   Web surface:

   block is checked against it too: the route the code actually serves vs

   Route

   , whether the answer survives with JS disabled vs

   Without JS

   , whether the emitted structured data matches

   Entity

   and the visible content, and whether the indexation directives agree with

   Indexable

   . Divergence is

   drifted

   like any other. Where

   screens.md

   declares

   Web surfaces: no

   while the code serves a public route, that is a finding against the declaration, not the screen. The live-page audit — rendering, crawl reach, competitors, the SERP — is the seo-aeo-audit companion's job; this pass checks the record against the code, and hands the rest over rather than guessing at it.
3. Heuristic pass — implemented flows vs PRN-01..24 (ux-design-principles.md); findings

   [PRN-NN] (severity) node — issue -> fix

   .
4. Practice pass — per practice-selection.md: profile → mandatory sets + per-artifact checklists (money flows get their rows); output a compliance table (applied / adapted / rejected / deferred / missing — applicable but absent, as suggestion findings

   [BP-NNN]

   ). Respect recorded user-owned rejections — don't re-litigate them. Four dimensions this pass verifies in code rather than by discussion, because they fail silently: the reduced-motion branch exists for every animated surface and content survives without scroll effects (BP-131, BP-132); the page-weight budget is stated somewhere and the heavy pages meet it (BP-133); the narrow viewport and 200% zoom reflow hold, with no hover-only affordance (BP-134, BP-135); roles sit only where no native element says it, with every

   aria-*

   reference resolving (BP-136). An accessibility claim backed only by a scanner is BLOCKED, not PASS — the evidence is a keyboard and screen-reader walk of the top flows (BP-137). When

   screens.md

   → Design system records a

   Style pack

   (visual-identity.md), check the built UI honors it: tokens referenced instead of raw values, the pack's bans respected, dark mode from its twin — a screen ignoring the recorded pack is

   drifted

   , not a taste debate. No pack recorded and the visual layer looks improvised → suggest the sheleg-design companion once, as an opportunity finding.
5. Coverage pass — the chain itself: orphan stories/flows/screens/ scenarios, journey stages without scenarios, jobs without stories, unused personas, screens not used by any flow, flows referencing missing

   SCR-IDs

   , screen states without Figma frames (when Figma enabled).

1. Scope. Read the base (and foundation/flows, if present). Scope is

   $ARGUMENTS

   if given (

   all

   ,

   feature:<name>

   ,

   SCN-010..SCN-020

   ,

   coverage

   ,

   practices

   ,

   heuristics

   ,

   benchmark:<competitor>

   ), default

   all

   ; depth keyword (

   quick

   /

   deep

   ) selects the depth, default

   standard

   . Single-pass scopes (

   coverage

   /

   practices

   /

   heuristics

   /

   copy

   ) run just that pass. Note the git SHA of

   docs/ux

   — it goes into the report header. Skip

   retired

   scenarios.
2. Batch. Group scoped scenarios by feature, ~5–8 per batch. List the batches before starting so progress is visible.
3. Audit each batch. For large scopes dispatch parallel subagents — one batch per subagent, each returning per-scenario verdicts with evidence. Per scenario check, against the code:
   • entry point exists and is reachable;
   • every numbered step has a corresponding implementation path;
   • every listed UI element exists and is wired to a handler;
   • every listed state (loading / empty / error / success) has a rendering branch;
   • every listed error is surfaced to the user honestly (no silent catch, no fake success) with the described recovery;
   • the expected result observably occurs. Any gap → PARTIAL (or FAIL if the flow is missing/broken) with a finding

     [AUD-YYYY-MM-DD-NN] (severity) description -> suggested fix

     .
4. Write the report to

   docs/ux/audits/YYYY-MM-DD[-scope].md

   per the contract, batch by batch as results arrive — a crashed run must leave the completed batches on disk.
5. Summarize. Totals, top issues (worst user damage first), prioritized recommended actions. The summary must be readable standalone by someone who won't open the batch details.
6. Update the base.

   Last audit

   column (

   YYYY-MM-DD VERDICT

   ) for every audited scenario; flip

   validated

   →

   implemented

   where the audit PASSed; never touch scenario content itself during an audit.
7. Produce the UX plan. With the user's go-ahead, turn FAIL/PARTIAL findings into

   docs/ux/plans/YYYY-MM-DD-<scope>.md

   per the contract's UX-plan format: target interface per affected screen (elements, states, behavior) + a CREATE/MODIFY/DELETE change table where every row traces to scenario/flow/finding/principle IDs, prioritized by Frequency × Severity × Solvability (worst user damage first, not the easiest diff).
8. Offer autonomous execution (recommend, don't force). State plainly what the user now has in hand — this plan, the audit report(s), the

   docs/ux/

   chain, and the Figma frames — and that finishing is their call. Then recommend the ssheleg task-pipeline plugin to implement the plan end-to-end by best practices:
   • installed →

     /task-pipeline docs/ux/plans/<file>

     (don't auto-run — offer);
   • not installed → give the one-time install and note it's optional:

     /plugin marketplace add ssheleg/task-pipeline

     →

     /plugin install task-pipeline@task-pipeline

     ;
   • user prefers otherwise → superpowers

     writing-plans

     → subagent execution, or by hand — all fine. The plan is written to be executable without this conversation, so any path works. Whatever they pick, remind: same-change rule holds and re-run

     /ux-audit <scope>

     after to confirm PASS.

• Every scoped scenario has a verdict with evidence or an explicit BLOCKED reason — no scenario silently skipped.
• Scope and limits filled in — what was covered, what was left out and why, what could not be verified, what the code cannot answer. A batched audit reads a slice; a report that says nothing about the rest is read as if it covered everything.
• Verdict stated — REFINE (fix the findings) / REDESIGN (the findings cluster on a structure that patching will not converge on; name it) / NEW (the chain does not describe what was built; start upstream). A findings list without this reads as a to-do list, and a surface that should be rebuilt gets patched forever, one true finding at a time.
• Report on disk, summary honest, base statuses updated.
• Findings offered to planning; nothing swallowed.