research-best-practices

# 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; `improve-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`
- `.webanatomy/research-best-practices/{topic}-{YYYY-MM-DD}/references/`

The HTML report is the primary visual output. Chat is only a short summary and pointer to the saved files.

If the environment cannot write files, explain the blocker and provide the report inline.

## Deterministic Report Renderer

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

- `.webanatomy/research-best-practices/{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/research-best-practices/{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} - what strong pages do`), no editorial framing
- optional `eyebrow`, `subtitle`, `target`
- `summary`: `string[]` of max 3 bullets (each max 140 chars): the section, where strong sits, and the tier you would start at. The first bullet renders as the "TL;DR:" lead sentence of the blue callout under the title.
- set `recommendationsHeading: "Improvement ladder"`.
- `recommendations`: `{ "title": "...", "why": "...", "how": ["..."], "refIds": ["..."], "priority": "HIGH|MEDIUM|LOW" }[]` - **the ladder: exactly three tier cards, ordered Tier 1 -> 2 -> 3, each building on the one below.** Title each `Tier N - {label}: {one-line gist}` with labels `Foundational`, `Competitive`, `Best-in-class`. `why` (max 220 chars) says what this tier unlocks over the tier below, tied to benchmark evidence ("3 of 5 references do X"). `how` is 1-5 imperative moves at that tier, each max 160 chars. `refIds` lists the benchmark sections that show the tier (screenshots render inline; 2-3 render as options A/B/C). `priority` is optional - use it for the conversion impact of reaching the tier, or omit. Optionally add a fourth card titled `Avoid` whose `how` lists the anti-patterns that keep this section stuck.
- `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. Label web-captured examples `[Web]` in the caption. References not claimed by any finding render in an "All references" gallery at the bottom.
- optional `gapAnalysis` (max 6 rows, cells max 90 chars), `currentSnapshot` (max 6 items, collapsed at the bottom), `working`, `footer`
- optional `ungrounded: true` - only for explicit no-MCP runs; lifts the floor of at least 3 findings carrying `refIds`

The renderer enforces the budgets and the grounding floor, and fails loudly with the exact overruns. When it fails, rewrite the content shorter; never pad, never bypass the renderer with hand-written HTML. Put anti-patterns in `recommendations` too (a finding whose `how` says what to avoid), and source notes in `footer`.

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

## Workflow

1. **Load context** - Read `.agents/webanatomy-context.md` when present.
2. **Confirm the one section** - Apply the scope guard above. Identify the single `section_type` (hero, pricing, testimonial, cta, faq, features, trust, etc.), the industry, and the target buyer. If the request is page/market/industry/competitor, hand to `find-examples`.
3. **Resolve industry and locale** - Always set an industry and locale before search: context first, explicit request second, fetched URL/page inference third, broad category fourth, `SaaS`/`B2B` and `en` fallbacks last.
4. **Search the section** - Use `search_sections` for that one section type. Run 3-5 angles: exact section in the industry, adjacent industry, broad market. Pull enough strong examples to span the range from table-stakes to standout.
5. **Inspect evidence** - Use screenshot URLs, strengths, and marker summaries to determine what is actually visible in each example.
6. **Build the ladder** - Sort the patterns into three tiers: **Tier 1 Foundational** (the table stakes this section must have to not lose), **Tier 2 Competitive** (what good pages add to win the click), **Tier 3 Best-in-class** (what the top sections do that most do not). Each tier is grounded in real benchmark sections; each builds on the tier below.
7. **Supplement current web research** - If browse/WebFetch is available, capture recent public examples for a tier. Label them `[Web]`, not benchmark examples.
8. **Write report and HTML** - Use relative image paths when references are downloaded.

## MCP Retrieval

Confirm the `webanatomy` MCP tools are available before searching. If connected, use live benchmark data. If not, tell the user up front ("Running without live benchmark data; using static guidance. Con