audit-page

# Audit Page

Diagnose the current state of a page, section by section, and tell the user which
sections to revamp first and why. Apply a proven CRO framework as the lens, but
organize the audit by SECTION so the output routes straight into the fix.

This is the **Audit altitude** of Web Anatomy: a whole-page diagnosis that runs standalone, with no benchmark data required. It feeds the grounded rework in `improve-page`.

You do NOT write copy, headlines, or rewrites here, and you do NOT need benchmark
data. Output is problem framing and prioritization: where conversion leaks and
what to fix first. This is the on-ramp. The grounded next step is where the real
edge is, so always end by handing off to it. There are two grounded paths and they
answer different questions, so Step 6 asks the user which one they want.

## Output Behavior

When file access is available, always write the orchestration handoff:

- `.webanatomy/audit-page/{page-or-section}-{YYYY-MM-DD}/scorecard.json` (your per-item judgments)
- `.webanatomy/audit-page/{page-or-section}-{YYYY-MM-DD}/score.json` (written by the scorer)
- `.webanatomy/audit-page/{page-or-section}-{YYYY-MM-DD}/audit.json`
- `.webanatomy/audit-page/{page-or-section}-{YYYY-MM-DD}/report.md`

`audit.json` is the machine handoff that improve-page reads so it does not
re-diagnose. The `score` block is copied verbatim from `score.json` (Step 3); do
not hand-edit those numbers. Use this exact shape:

```json
{
  "schema": "webanatomy.audit-page.v2",
  "target": "<url or page name>",
  "industry": "<resolved or inferred industry>",
  "locale": "en|fr",
  "score": {
    "overall": 0,
    "band": [0, 0],
    "coverage": 1,
    "evidenceBacked": 1,
    "evaluated": 49,
    "naCount": 0,
    "categoryScores": [
      { "category": "Hero", "score": 0, "passCount": 0, "failCount": 0, "naCount": 0, "failedItemIds": [] }
    ]
  },
  "currentSnapshot": [{ "label": "Headline", "text": "..." }],
  "strengths": [
    { "section": "trust", "what": "Recognizable customer logos sit above the fold", "why": "fast credibility for a cold visitor; keep it" }
  ],
  "recommendations": [
    {
      "section": "hero",
      "severity": "HIGH",
      "kind": "copy",
      "opportunity": "Lead the H1 with the outcome, not the product name",
      "why": "what it unlocks, tied to the real page",
      "failedItemIds": ["hero.outcome_focus"]
    }
  ],
  "pageLevel": [
    { "section": "page", "opportunity": "Fix the narrative order (pain then outcome then product)", "why": "..." }
  ],
  "sectorSpecific": [
    { "section": "contact", "opportunity": "Surface the capital-loss risk notice near the form", "why": "regulated finance; judgment, not the rubric" }
  ],
  "startHere": "hero",
  "notes": "industry inferred; capture method + confidence"
}
```

Note the split: the `score` block comes from the rubric and the scorer (Step 3,
facts). `recommendations` come from the free CRO audit (Step 4, judgment) and are
NOT derived from which rubric items failed. The optional `failedItemIds` on a
recommendation is a cross-reference only (so improve-page can target exact gaps),
not the source of the recommendation. Attach the rubric items a recommendation
relates to when there is a clean match; leave it off for judgment or sector moves
that the rubric does not cover.

`report.md` is the short human-readable version (the prioritized list below). Chat
is a one-line summary plus the start-here section.

## Two independent tracks (do not let one drive the other)

This skill produces two things by two different methods, and they must stay
dissociated:

1. **The score (facts / overview).** Run the rubric in `references/scoring.md` to
   get the overall score + category scorecard. This is the factual best-practices
   read whose job is to prove the page needs a revamp. Mechanical.
2. **The recommendations (substance).** Do a free, expert CRO audit using
   `references/cro-audit.md` (the page-cro-equivalent lens) and your judgment.
   These are NOT derived from which rubric items failed — deriving recos from the
   checklist gives detailed-but-mediocre output. A free expert read gives sharper,
   higher-ROI recommendations.

Score one way, recommend another way. They meet only at output (Step 5): score on
top as the proof, recommendations below as the substance.

## Step 1 — Context (optional, do not block)

Check `.agents/webanatomy-context.md` for product, ICP, conversion goal,
industry, and locale. If missing, proceed from the URL, screenshot, or codebase
with conservative assumptions. Context makes the problem framing specific instead
of generic; use it when present, never require it.

## Step 2 — Get the page accurately (capture, then verify in the DOM)

Prefer a canonical server capture when available: if a `capture_page` MCP tool
exists, use it — it returns reliable desktop + mobile screenshots plus
DOM-extracted structure (headings, CTAs, form fields, sections). That is the
trustworthy path and it sidesteps the failure mode below.

If you must render it yourself (no capture service), follow this recipe exactly —
a single quick screenshot is NOT enough and will lie:

1. Navigate, then **wait for network idle** so JS/iframe embeds (forms, widgets,
   proof) finish loading. Landing-page forms are often third-party embeds
   (HubSpot, Calendly) that paint after first render.
2. **Dismiss cookie/consent overlays** (Axeptio, OneTrust, etc.) — they cover the
   hero and block both the screenshot and the form.
3. **Scroll the full page** to trigger lazy-loaded sections, then screenshot
   (above-the-fold and full-page).
4. **Verify presence/absence in the DOM, never from the screenshot alone.** Query
   the DOM for form fields (`input`/`select`/`textarea`), CTAs (buttons/links),
   and section anchors. A screenshot taken too early shows a form as "missing"
   when it is actually in the DOM — do not make that mistake.

**Hard rule: never assert an element is missing from a screenshot.** "No form",
"no C