/audit

name: audit
description: Full three-perspective audit of an existing website from one URL — design (tensions + concrete improvement opportunities), SEO/technical, and LLM/AI-search visibility — plus Core Web Vitals, synthesized into a scored, evidence-bound report. Use when the user asks to "audit this site", "site audit", "design audit", "SEO audit", "why is my site underperforming", "LLM visibility", "how does my site look to AI", or invokes /stardust:audit <url>.
license: Apache-2.0

stardust:audit

One URL in. One scored, evidence-bound audit out.

`audit` looks at an existing website from three perspectives — design (brand tensions + concrete improvement opportunities), SEO/technical, and LLM/AI-search visibility — measures Core Web Vitals, and synthesizes everything into a seven-dimension scorecard plus a prioritized findings ledger that tells the owner what to improve to generate a better business outcome. The report is also the natural seed for a redesign: its findings feed `stardust:uplift`'s improvements list and `stardust:direct`'s Phase 2.5, and it closes with uplift-shaped redesign directions so "run `stardust:uplift`" is the obvious next step.

Opinionated defaults

• **Multi-page by default** — `stardust:extract <url> --cap 8`

(home + seven IA pillars) unless `--single` or `--pages` overrides.

• **Non-interactive** — the audit never asks questions. Every

assumption it makes instead is recorded in `audit.json#assumptions` and stated in the report's executive summary.

• **Evidence-bound** — every claim cites a measurement, a `T-*`

tension id, a check result, or a screenshot observation. A claim with no citation does not ship.

• **No fabricated data** — a measurement that could not be taken is

reported as `not measured (<reason>)`, never estimated silently. An estimate, where reasoned, is labeled as one with its basis.

• **Graceful degradation, not failure** — optional capabilities

(refero, marketing-skills, modern-web-guidance, PageSpeed Insights) are probed once and their absence is recorded, never fatal. See § Degradation ladder.

Inputs

• `<url>` — required. The site to audit. A path narrows the crawl to

that subtree (extract's semantics).

• `--pages <n>` — optional. Override the default 8-page extraction

cap (passed through as `--cap <n>`).

• `--single` — optional. One-page audit of the given URL only. The

cross-page checks (duplicate titles, sitemap coverage, CTA fragmentation across pages) then run on a single page and say so.

• `--deploy` — optional. After the report renders, publish

`report.html` as a single self-contained page via the DA transport (`../deploy/da-deploy-protocol.md`: source PUT → preview → live) and print the delivered URL. Transport only — the report never goes through deploy's section→block conversion, which would decompose the self-contained file.

• `--benchmark` — optional. Force Phase 5 reference benchmarking:

probe the refero MCP even when the earlier capability probe was slow or ambiguous. Without this flag Phase 5 fires only when the probe succeeds quickly.

There are no other flags. Everything else is derived from the captured surface or governed by the underlying skills' contracts.

Phase 0 — Setup

1. Run the master skill's setup (`../stardust/SKILL.md` § Setup) — with one audit-specific carve-out: **impeccable absence is a degradation here, not the master setup's hard stop.** When the dep check fails, record `impeccable: unavailable` in `audit.json#degradations` and continue — Phase 2 runs without the critique/audit arms (VISION pass + accessibility fold-in still fire) and Phase 6 skips the report render; the run ends at stop condition (b) *after* `audit.json` is written. 2. **Extraction freshness check.** If `stardust/current/` holds an extraction of the **same origin** less than **7 days** old — origin from `stardust/state.json` (the site record extract stamped), recency from the newest `pages/<slug>.json#_provenance.fetchedAt` — reuse it and record `site.extraction.reused: true`. Otherwise invoke `stardust:extract <url> --cap 8` (or `--single` / `--pages <n>` per the inputs). Extract owns the crawl, the screenshots, `_brand-extraction.json`, `pages/<slug>.json`, `PRODUCT.md` / `DESIGN.md`, and `brand-review.html` with its Tensions section. 3. **Probe optional capabilities once**, recording each outcome in the degradation record (`audit.json#degradations`):

• `marketing-skills` plugin (`seo-audit`, `ai-seo` skills present?)
• `modern-web-guidance` (`npx -y modern-web-guidance@latest search

"<query>"` responds?)

• refero MCP (attempt `mcp__refero__refero_search_styles`; treat a

tool-not-found or timeout as unavailable)

• PageSpeed Insights API (network-reachable without a key?)
• rollout project (`stardust/rollout/rollout.json` present?)

If extract fails entirely (site unreachable, bot-management block past the headed-Chrome fallback), stop and surface extract's error verbatim — there is nothing to audit. This is the only hard stop before synthesis; see § Stop conditions.

Procedure

Phase 1 — Brand surface & tension analysis

Read `stardust/current/_brand-extraction.json` and `stardust/current/brand-review.html` § Tensions surfaced (rule catalog in `../extract/reference/brand-review-template.md` § Tensions). Every fired `T-*` tension is candidate evidence for a finding — carry the ids forward, do not re-derive the detections.

Compute the four brand-expression measurements the report needs. Each lands in `audit.json#measurements` with `status` + `method` per `reference/report-format.md`:

• **`brandColorShare`** — brand-color share of painted pixels on the

captured home screenshot. Preferred method: Playwright pixel sampling (`method: "pixel-sample"`) — load the screenshot, sample a grid (e.g. every 8th pixel), classify each sample to the nearest palette entry within a tolerance, a