feature-guide

name	feature-guide
description	Produce a shareable, non-technical feature guide as a published Artifact — live screenshots of every surface in the feature's story, captured from the running dev app with Playwright (including interaction states: open menus, drawers, drill-downs), annotated with numbered callout dots and plain-language legends, organized around the feature's own mental model (levels, flow, or lifecycle), with "reading the numbers", "what it can't show (yet)", and "who can see it" sections. Self-contained HTML (base64-embedded images, light + dark themes, project brand tokens) published via the Artifact tool and iterated in place at the same URL.
allowed-tools	["Read","Write","Edit","Glob","Grep","Artifact","AskUserQuestion","ToolSearch","Bash(mkdir:*)","Bash(ls:*)","Bash(npx tsx:*)","Bash(npx playwright:*)","Bash(sips:*)","Bash(cwebp:*)","Bash(ruby:*)","Bash(node:*)","Bash(curl:*)"]
when_to_use	Use when the user wants a shareable, screenshot-driven explanation of a shipped UI feature for an audience beyond the codebase — teammates, stakeholders, non-technical readers. Triggers: "make a report for my team showing X", "document the new X feature with screenshots", "create a feature walkthrough I can share", "write up the X feature for the team", "make an announcement page for X". Applies whenever the deliverable is a standalone guide/report with images of the app, not code docs or a README.
argument-hint	<feature name or short description>
arguments	["feature"]

Feature Guide — annotated-screenshot walkthrough as a published Artifact

Turn a shipped UI feature into a guide a mixed audience can follow: real screenshots from the running app, numbered annotations, and copy that explains what the reader sees — published as a private-by-default Artifact the user can share and keep iterating at the same URL.

Inputs

• $feature: the feature to document (name or short description). The surfaces, audience notes, and any extra sections come from conversation context; ask if the story is unclear.

Goal

A published Artifact URL containing: one annotated screenshot per surface in the feature's story (including interaction states), non-technical body copy, a structure that mirrors the feature's own mental model, honest limitations, an access/permissions section, and a footnote stating the screenshots use synthetic data. The user can request edits and get them at the same URL.

Hard rules

• Demo data only. Screenshots must show synthetic/demo records, never real customer names or figures. If the dev DB mixes real and demo data, choose demo records; if none exist, stop and ask before seeding. The guide always footnotes that data is synthetic.
• Non-technical by default. Body copy is written for a mixed audience: no routes, class names, or schema talk in prose (a path chip for "where to click" is fine). Explain domain terms on first use.
• Honest numbers. If the feature has known data limitations, the guide says so plainly (its own section), including what would unlock them.

Steps

1. Scope the story

Identify the surfaces that tell the feature's story: pages, and the interaction states that don't exist at rest (an open menu, an open drawer, a hover state, a filled form). Order them by the feature's own mental model — drill-down levels, a workflow left-to-right, a lifecycle. Check the repo for plans/ADRs/memory that record what the feature is and any known limitations or access rules; these feed sections later.

Human checkpoint: present the surface list + narrative order and get confirmation before capturing anything.

Success criteria: a confirmed list of screenshots to take, each with its URL, required state (what's open/clicked), and the 2–4 things to annotate.

2. Stage demo data

Find records that make every surface look real and populated — hierarchies with children, tables with rows, charts with slope. Query the dev DB (MCP execute_sql tool, just psql, or rails runner) to verify the records exist and have data in the window the feature displays.

Artifacts: the concrete IDs/identifiers each screenshot will use.

Success criteria: every surface on the list has a named demo record that renders non-empty.

3. Capture screenshots with Playwright

Write a one-off Playwright script and run it against the local dev server:

• Put the script inside the repo (e.g. tmp/) — module resolution for @playwright/test fails from outside; delete it when done.
• Reuse the project's e2e auth helper (login URL, selectors, seeded credentials — e.g. e2e/helpers/auth.ts) rather than inventing a login.
• Viewport ~1600×1000 with deviceScaleFactor: 2 for crisp retina output.
• For each surface: goto, waitForLoadState('networkidle'), extra waitForTimeout for charts/animations, then screenshot.
• Interaction states are their own shots: click the menu/row, wait ~400ms, screenshot.
• Output PNGs to the session scratchpad.

Success criteria: the script exits cleanly and one PNG per confirmed surface exists.

4. Verify every shot and plan annotations

Read each PNG and actually look at it: logged-in state, right record, right data, nothing embarrassing in view (browser chrome, other tabs, real data). Retake anything wrong. While viewing, note annotation coordinates for each callout as percentages of width/height — they position the numbered dots.

Success criteria: every screenshot verified good; a dot list per image with left%, top%, and legend text.

5. Build the page

Load the artifact-design skill first (required before Artifact), then:

• Brand tokens: pull the project's palette/type from its design system (variables file, CLAUDE.md brand section). Define tokens on :root, redefine under @media (prefers-color-scheme: dark) and both :root[data-theme="…"] overrides. Skip webfont CDNs (CSP); use a close system stack.
• Images: downscale to ~1600px wide JPEG (sips -Z 1600 -s format jpeg -s formatOptions 82), embed as base64 data URIs (CSP requires self-contained). Keep the total page under a few MB.
• Annotated figures: each screenshot in a bordered, shadowed frame; absolutely-positioned numbered dots at the step-4 coordinates; a legend below matching dot numbers to plain-language explanations.
• Structure: intro (what + why) → mental-model overview (level map / flow strip) → one section per surface with its figure → "reading the numbers" (how to interpret) → "what it can't show (yet)" if limitations exist → "who can see it" (roles table) → quick reference → synthetic-data footnote.
• Write the HTML to the scratchpad; build with placeholder tokens and inject base64 via a small script rather than pasting megabytes by hand.

Success criteria: a self-contained HTML file, no external requests, both themes styled, every confirmed surface present with annotations.

6. Publish and iterate

Publish with the Artifact tool (stable emoji favicon, one-line description, short version label). Report the URL and note it's private until shared from the page's share menu. For any follow-up edit: edit the same file and republish the same path — same URL, new version label. Delete the temp Playwright script from the repo.

Success criteria: a live Artifact URL delivered to the user; subsequent edits land at the same URL.