GabrielAmz/web-anatomy

# 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 `write-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.

# Build Page

The last step of the page workflow: turn structure + copy into a wireframe someone can actually look at. `write-page` produces the words; `build-page` lays them out in a coherent design and hands the user one shareable artifact.

This is the **terminal assembler**. It runs on both branches:

- **After a new page is written (create):** assemble the chosen sections + their copy into a wireframe.
- **After an existing page is improved:** assemble the improved structure + copy into a shareable "here is the better version" wireframe (optional; the user can stop at the copy fixes).

It does not write copy (that is `write-page`), it does not diagnose (that is `audit-page`), and it does not invent the section list (that comes from the structure it is handed). It assembles and designs.

## The one rule: a single design exemplar

A coherent page cannot be stitched from sections of different companies. Their type, color, and spacing clash, and the result reads as broken. So `build-page` derives the whole design system from exactly ONE source:

# Find Examples

Pull the strongest real pages and sections in a market and hand back what to steal.

This is the **Page altitude** of Web Anatomy: the market view. What the best pages in an industry do (structure, positioning, proof, copy), and how the user's own page compares when they share it.

## Two modes

- **Discover (default).** The user wants inspiration or a swipe file. Retrieve, filter, group by pattern, and give them the best examples to open. No page of their own required.
- **Compare.** The user shares their URL, screenshot, or page and wants to see how it stacks up. Do everything Discover does, then add a light gap read: how their page compares to the benchmark winners, labeled HIGH/MEDIUM/LOW, plus what is already working. If a recent `audit-page` report exists for that target, use its findings to make the comparison specific; if not, keep it lighter and more general. This is the merged home of the old benchmark-compare.

Both modes stay lighter than `research-best-practices`, which goes deep on one section with a tiered ladder. This skill is the market scan; that one is the section deep-dive. For the grounded rework or the build, hand off to `write-page`.

**Building a new page?** This is where the user picks the exemplar. Surface the top homepages for the industry, let them choose ONE whose layout they want to follow, and hand off: its section order seeds the structure for `write-page` build mode, and the same exemplar drives the design in `build-page`. One pick, used twice (structure, then look). The benchmark has no stored page structure, so the exemplar's own section order is the source.

# Moodboard

Assemble a section-by-section visual moodboard for a page. For every section the report shows the current state large, the problems identified beside it, a grid of benchmark screenshots each captioned with the practice it demonstrates, the best practices grouped by discipline, and the recommendation for the brand.

This is the **page altitude, visual-first** output of Web Anatomy. It generates its own content: it captures the live page section by section (the same on-page reading `audit-page` does) and pulls benchmarks per section from the MCP (the same retrieval `find-examples` does), then composes both into one scrollable board.

## How moodboard differs from the neighbors

Keep the routing clean. The closest neighbor is `benchmark-compare`, and they share the same MCP retrieval underneath, so the distinction matters.

- **`benchmark-compare`** takes **one** target (a URL, screenshot, or pasted section) and returns a **verdict**: a gap analysis where each gap is labeled `HIGH`, `MEDIUM`, or `LOW`. The screenshots are evidence for the gaps. Use it to answer "how far is this from the winners, and what is the biggest gap."
- **`moodboard`** takes the **whole page** and returns a **reference board**: every section in scroll order, the current state large beside the problems, and a grid of benchmark screenshots as the centerpiece. The screenshots are the point. Use it to answer "what should each block look like, as a brief I can hand to design or import into Figma." It does not score gaps.
- **`find-examples`** is one section's swipe file. **`research-best-practices`** is a narrative report. **`improve-page`** is a grounded rework with copy-paste fixes.

# Research Best Practices

Produce a benchmark-backed research artifact for ONE section, not just chat. The goal is to answer: for this section, what does strong look like, and what are the levels the user can climb to, each grounded in real benchmark sections.

This is the **Section altitude** of Web Anatomy: take a section the user already knows they want to work on and return a tiered improvement ladder. The user picks a tier; `write-page` executes it.

**Scope guard.** This skill is for one section. If the request is about a whole page, a market, an industry, positioning, or competitors, that is `find-examples` (the Page altitude) — route there. If the user named a page but no section, ask which section to start with before researching. Confirm the single section first.

## Output Behavior

Always write:

- `.webanatomy/research-best-practices/{topic}-{YYYY-MM-DD}/report.md`
- `.webanatomy/research-best-practices/{topic}-{YYYY-MM-DD}/report.html`

# Web Anatomy Setup

You are the optional context loader for Web Anatomy. Your job is to capture enough product and market truth that benchmark-backed skills can retrieve better examples and avoid generic CRO advice.

This setup improves recommendation quality, but it is never mandatory. If the user wants a quick audit, examples, or benchmark comparison, let the relevant skill continue from the URL, screenshot, pasted copy, or available context.

This is the **Foundation** the four altitudes (page, audit, section, fix) build on. The more product and market truth it captures, the sharper every downstream skill.

## Step 0 - Check For Updates (best-effort, non-blocking)

Skill packs do not auto-update: a user who installed a while ago is running an old copy until they re-install. Since setup is the natural entry point, do a quick version check here. Keep it best-effort, never block setup on it.

1. Read the installed pack version from `references/pack-version.txt` (resolve relative to this `SKILL.md`).
2. Fetch the latest published version from GitHub: the `tag_name` from `https://api.github.com/repos/GabrielAmz/web-anatomy/releases/latest` (or read the tag at `https://github.com/GabrielAmz/web-anatomy/releases/latest`). Strip a leading `v`.

# Write Page

Classify -> capture -> route -> benchmark -> write. The flagship Web Anatomy copy engine: it writes the grounded words for a page, whether reworking an existing one (improve) or building a new one (build).

This is the **Fix altitude** of Web Anatomy: it turns a direction into grounded, copy-paste changes anchored to real benchmark pages, not generic advice. It is the executor the other skills hand off to. For a new page, `build-page` assembles what this skill writes into a shareable wireframe.

## Two modes

This skill runs in one of two modes. Detect which from the request and the available inputs:

- **Improve mode (default).** An existing page or section. Capture its current reality, gap it against the benchmark, and write the fixes. This is the path when the user has a live URL, a screenshot, pasted copy, or a page in their codebase.
- **Build mode.** A new page or section that does not exist yet (the create lane). There is no current reality to capture and no gap to measure. Take the chosen structure (a user-picked section list, a `find-examples` structure, or a `research-best-practices` tier) as the build spec, and write the sections from scratch, grounded in the same benchmarks. Skip the current-reality capture (Step 2) and the gap-vs-current framing; everything else (benchmark grounding, copy/design shaping, the report) is the same. If no structure exists yet, resolve it first with the light outline below. After the copy is written, the natural next step is `build-page`, which assembles the structure + this copy into a shareable wireframe.

### Build-mode structure (the light outline)