find-examples

# 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 `improve-page`.

## Output Behavior

Always create a lightweight visual artifact:

- `.webanatomy/find-examples/{topic}-{YYYY-MM-DD}/report.md`
- `.webanatomy/find-examples/{topic}-{YYYY-MM-DD}/report.html`
- `.webanatomy/find-examples/{topic}-{YYYY-MM-DD}/references/`

The chat response is only the summary and file pointer. Do not dump the whole swipe file into chat.

If the environment cannot write files, explain the blocker and provide a compact inline version.

## Deterministic Report Renderer

When file access is available, do not hand-write the final HTML. Write structured report data first:

- `.webanatomy/find-examples/{topic}-{YYYY-MM-DD}/report-data.json`

Then run the shared renderer from this skill pack:

```bash
node <skill-dir>/scripts/render-report.mjs --input=.webanatomy/find-examples/{topic}-{YYYY-MM-DD}/report-data.json
```

Resolve `<skill-dir>` relative to this `SKILL.md`. The renderer validates the report data, downloads every `screenshotUrl` into `references/`, writes `report.md`, writes `report.html`, and renders "screenshot unavailable" when no screenshot exists.

Use this report-data shape (v2):

- `title`: plain and descriptive (`{Topic} - benchmark examples`), no editorial framing
- optional `eyebrow`, `subtitle`, `target`
- `summary`: `string[]` of max 3 bullets (each max 140 chars) on what the examples show. The first bullet renders as the "TL;DR:" lead sentence of the blue callout under the title.
- `recommendations` used as **patterns** (set `recommendationsHeading: "Patterns"`): `{ "title": "...", "why": "...", "how": ["..."], "refIds": ["..."] }[]` - one entry per plain-English pattern. `title` is the pattern name; `why` (max 220 chars) is what makes it work; `how` is 1-5 adaptation bullets, each max 160 chars; `refIds` lists the example references showing it (their screenshots render inline; 2-3 render as options A/B/C). Skip `priority`/`kind`/`prompt`; this is a swipe file, not an audit.
- `references`: `{ "id": "...", "title": "...", "company": "...", "section": "...", "sourceUrl": "...", "screenshotUrl": "...", "caption": "...", "insight": "..." }[]` - `id` is a stable kebab-case slug; `insight` is the one-line what-to-notice, max 200 chars. References not claimed by a pattern render in an "All references" gallery at the bottom; for a flat ranked list, leave `recommendations` empty and let all references render in the gallery.
- `gapAnalysis` (**compare mode only**): `{ "dimension": "...", "current": "...", "strongPattern": "...", "gap": "HIGH|MEDIUM|LOW" }[]`, max 6 rows, `current` and `strongPattern` max 90 chars each. The light read of the user's page against the benchmark winners. Omit in discover mode.
- `currentSnapshot` (**compare mode only**): `{ "label": "...", "text": "..." }[]`, max 6 items, the user's current page facts; rendered collapsed at the bottom. Omit in discover mode.
- `working` (**compare mode only**): `string[]` of 2-4 bullets, what the user's page already does well. Omit in discover mode.
- optional `footer`
- set `ungrounded: true` only on explicit no-MCP runs

The renderer enforces the budgets and fails loudly with the exact overruns. When it fails, rewrite the content shorter; never pad, never bypass the renderer with hand-written HTML.

Only fall back to hand-written HTML if the renderer cannot be run.

## Inputs To Infer

Infer these from the request and `.agents/webanatomy-context.md` when available:

- scope: whole homepage/landing page inspiration vs individual section pattern
- page type: homepage for whole-page benchmark examples in v1
- section type: hero, pricing, testimonial, value_proposition, cta, features, trust, faq, integrations, use_cases
- industry: user's context first, then request/URL/page inference, then broad fallback
- locale: request/page language first, then default `en`
- intent: swipe file, redesign inspiration, competitor reference, or section pattern

If the request is for homepage or landing page examples, set scope to whole page and use `search_pages` first. If the section type is unclear for a section-level request, map aliases:

- "above the fold" -> hero
- "customer proof" -> testimonial or trust
- "plans" -> pricing
- "logos" -> trust
- "value prop" -> value_proposition
- "use case" -> use_cases
- "CTA band" -> cta

Ask one clarifying question only when the same request could map to different section types and the difference matters.

## Compare Mode (when the user shares their own page)

Trigger compare mode when the user gives a URL, screenshot, pasted copy, or local page and wants to know how it stacks up ("compare my page", "how far are we from the best", "gap analysis"). Discover mode runs first (find the market winners); then layer the comparison on top.

1. **Capture the user's page.** If a URL, fetch or browse it before compa