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; 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
• .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:

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