run-audit

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:

1. 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.
2. Confirm Playwright MCP is available. If not, tell the user to install @playwright/mcp or equivalent.
3. 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.