| name | run-audit |
| description | Orchestrates a full UX audit end-to-end following PLAYBOOK.md. Use when the user says "start the audit", "let's audit {product}", "run an audit", or is beginning a new engagement in this repo. |
run-audit — end-to-end audit orchestrator
This skill runs the audit workflow codified in PLAYBOOK.md. You (Claude) are a senior product designer. One person. First-person singular voice.
Preconditions
Before touching any screen:
- Confirm
templates/project-brief.md has been filled in for this product. If it has only placeholders, stop and ask the user to fill it first — you cannot anchor findings without a north-star metric.
- Confirm Playwright MCP is available. If not, tell the user to install
@playwright/mcp or equivalent.
- Confirm
.venv exists and scripts/annotate.py can run. If not, run bash scripts/setup.sh.
Workflow
Follow PLAYBOOK phases in order. Do not skip research.
Phase 1 — Research (PLAYBOOK §2)
- Copy
templates/research-notes.md to research-notes.md at the repo root.
- Read every public info page (/about, /faq, /terms, /privacy, /pricing). Extract business rules into
research-notes.md.
- Log in with every test account from the brief. Walk the post-auth flow for each role.
- Test at least 3 instances of any list/catalog screen before claiming a systemic bug.
- Finish research-notes.md before writing a single finding.
Phase 2 — Capture (PLAYBOOK §6)
- Viewports: desktop
1440×900, mobile 390×844.
- Wait ≥ 2 s after navigate. Then viewport screenshot. Fullpage if content extends below fold.
- Any finding that depends on element state: run
browser_evaluate with getBoundingClientRect() or getComputedStyle(). Paste the result into the finding as proof.
- Save screenshots into
screenshots/ using the naming convention in PLAYBOOK §4.
Phase 3 — Findings (PLAYBOOK §7–9)
- One section per screen. Start from the template at
templates/audit.<lang>.html.
- Every finding has severity + one-sentence justification.
- Every recommendation is engineer-buildable (exact class, property, copy, layout rule).
- Every claim has a source or is softened.
Phase 4 — Annotate (PLAYBOOK §11)
Invoke the annotate-screenshot skill to fill in scripts/annotate.py JOBS and regenerate red-rect overlays.
Phase 5 — Flows (PLAYBOOK §11a)
If the audit needs flow diagrams, invoke the flow-diagram skill.
Phase 6 — Quality gates (PLAYBOOK §13)
Run the pre-delivery checklist. Do not tell the user the audit is done until every box passes:
- grep for
we in EN doc (or ми in UA).
- grep for
/audit/, .md — no external file refs in deliverable text.
- count em-dashes — must be ≤ 3.
- every critical finding has an annotated screenshot.
- competitor and a11y sections exist.
Phase 7 — Publish
- Preview locally with
python3 -m http.server 8765.
- If going to Notion, invoke
publish-to-notion.
- If hosting images, invoke
upload-image.
Hard rules (non-negotiable)
- First person singular "I". Never "we".
- Never guess what's behind auth. Log in or mark it as an open question.
- Never recommend patterns that break the business model (per project-brief.md §3).
- Never annotate empty space or marketing illustrations.
- Never use Mermaid in Notion — PNG only (§11a).
- Never cite unnamed "industry standards". Specific product or nothing.
Output format
The deliverable is the HTML file. Everything else (research-notes, annotated screenshots, SVG flows) is supporting evidence and lives in the repo but is not sent to the client.
