/feature-walkthrough

name: feature-walkthrough
description: Capture a finished feature as live screenshots and assemble them into a shareable walkthrough page for review. Use when someone needs to see a feature working but a live demo isn't possible — a reviewer in another timezone, a stakeholder who wants to look before a rollout, a PR whose value doesn't survive a diff. Produces a published artifact, not a slide deck.

Feature walkthrough

Drive a feature through every state that matters, screenshot each one from the real app, and assemble them into one page a reviewer can read start to finish. The output is a published Artifact — a private URL the author can share.

This is a **demo substitute**, not a test report. If the question is "does it work", run the tests. If the question is "is this the right product", this is the shape that answers it, because the reviewer sees the screens rather than a description of them.

⚠️ Dev database only — never production

Every step below **writes**: seeding a scenario needs contributor rows, invites, lapsed flags and half-finished states that no real account should ever be put into, and the restore at the end deletes rows. Doing that against production would corrupt real users' data.

Before the first write:

1. Confirm the app you are driving points at a **dev database**, and that the query tool you seed with points at the same one. Check the connection your `.env` actually resolves to — do not trust a log line that says which database it is. 2. Re-check after any long gap. The `postgres-query` skill's target can be re-pointed between sessions, and a "dev" fingerprint taken an hour ago is not evidence about the query you are about to run. 3. Never pass a writable flag to a production target. If you cannot tell which target you have, stop and ask.

Also assume the screenshots are **going to be shared**. Anything on screen — usernames, avatars, collection names, item thumbnails — leaves with the report. Prefer dev accounts whose content is unremarkable, and read the captures before publishing rather than after.

Setup

Copy `.env.example` to `.env` in this directory and adjust if your ports differ. It is gitignored; every developer supplies their own. Nothing in it is secret.

Screenshots default to a temp directory, outside the repo. If you point `SHOTS_DIR` somewhere else, keep it outside the checkout — the captures show dev accounts and their content, and this repo is public. `/shots/` and `**/walkthrough-shots/` are gitignored as a backstop, not as permission to write there.

You need three things running:

• the app and, for anything behind sign-in, the auth hub — see the **`dev-server`** skill
• the **`browser-automation`** server, which gives you one session per user so you can hold

several signed-in accounts at once

• the **`postgres-query`** skill for seeding and for verifying the restore

Signing a session in as a given user is covered by `browser-automation` and the dev-login notes in memory; it is deliberately not restated here.

The loop

**1. List the states before you touch anything.** Write them down. Every state a screenshot has to prove, including the empty, blocked and refused ones — those are usually the interesting half and the easiest to forget. Note which are one-way.

**2. Seed the scenario.** Multi-user features need states the UI cannot reach on its own (someone already holding a role, an invite sent six days ago, a lapsed subscription). Seed those directly, and keep a note of every row you create — that note is your restore script.

**3. Capture, in dependency order.** This is the step people redo. A pending state has to be shot *before* it is accepted; a blocked state before the block is lifted. Get the order wrong and you re-seed the whole scenario. Sequence the one-way transitions first, then everything reversible.

**4. Build the page.** A template with `{{shot-name.png}}` placeholders, then:

node .claude/skills/feature-walkthrough/build-report.mjs report.template.html shots/ report.html

**5. Publish and hand it over.** See below — the sharing step has an order to it.

**6. Restore, and verify the restore.** Delete what you seeded, put changed columns back, then **query for the rows again** and confirm they are gone. Report anything you deliberately left behind and why.

Publishing, and the sharing handshake

Publish the built file with the **Artifact** tool. It is the right vehicle for this: one scrollable page, screenshots inline, a URL that keeps working, and it updates in place.

Artifact(file_path: "report.html", favicon: "🤝", description: "<one line for the gallery card>")

Keep the **file path and favicon stable** across redeploys. Same path means the same URL, so a reviewer who already has the link keeps seeing the current version; a changed favicon reads as a different page to anyone who kept the tab open.

**Artifacts are private until the author shares them**, and an agent cannot share on their behalf. That ordering catches people out, so do it deliberately:

1. Publish, and give the author the link. 2. Say plainly that it is private until they open it and use the page's share menu. 3. Only **after** they confirm it is shared, send the link onward.

Announcing the link to a reviewer before that step gives them a URL they cannot open. If you are sending the message yourself, wait for the confirmation.

To update a walkthrough from a later session, pass the existing artifact's `url` — publishing without it creates a second artifact rather than updating the first, and the reviewer's link goes stale. Use `action: "list"` to find the URL if you do not have it.

If an artifact isn't the right vehicle

It usually is, but the alternatives have real trade-offs:

| Instead | Worth it when | Costs | | --- | --- | --- | | **Link it from the PR** | Reviewers live there, and it outlives the chat | Screenshots can't be embedded from the CLI, so this is a link *to* the artifact,