/walkthrough

name: walkthrough
description: Generate a hands-on browser walkthrough of a PR's user-facing changes to exercise before review; --publish posts the final version to the PR for QA.
argument-hint: "[PR-number-or-branch] [--publish]"

Walkthrough

Generate a concise, click-by-click manual walkthrough of the current branch's user-facing changes, so the human orchestrator can exercise the feature in a browser **before** the formal `/code-review`. Seeing a feature work is faster than reading code or a PR description for catching UX problems.

This skill does not modify code or perform code review. It renders the walkthrough as a single self-contained **HTML** file — with click-to-copy commands, URLs, and logins — in **both** modes. By default it writes that HTML to the project's local `tmp/` as scratch and opens it. With `--publish` it also uploads the HTML to the project's configured QA host (when one is declared in the project's `CLAUDE.md`) and posts a PR comment linking to it, with a Markdown rendition as a collapsible fallback (Markdown is the only thing a GitHub comment can render inline).

**Where it sits in the workflow — two slots:**

• **Generate** (default) — run after `/create-pr` and before `/code-review`, and re-run as needed. The orchestrator's iterative pre-flight check.
• **Publish** (`--publish`) — run once after `/code-review` and any review fixes, just before merge (or after merge, to backfill a walkthrough that was missed). Posts the final walkthrough to the PR so the QA tester can follow it after deploy.

**Not the same as:**

• `/debrief` — a heavy architecture and test-coverage write-up for milestones.
• `/qa-handoff` — a broad, committed QA guide for a whole phase. `/walkthrough --publish` is the per-PR counterpart: one change, posted to the PR.

Command Options

• `--publish`: Post the final walkthrough as a comment on the PR, regenerating it first so it matches the code under review. Run once, after review — normally just before merge, but it also works on an already-merged PR to backfill a missed walkthrough. See the Publishing section.

Your task

If invoked with `--publish`, follow the **Publishing the final walkthrough** section below instead. Otherwise, generate a new walkthrough:

1. Identify the change set

• If a PR number or branch is given as an argument, use it. Otherwise use the current branch against its base (`main`/`master`).
• Get the diff and changed files: `gh pr diff <N>` for a PR, or `git diff <base>...HEAD`.
• Note the open PR number for the branch, if any (`gh pr view`).

2. Gate: is a walkthrough applicable?

Classify the diff:

• **User-facing** — changes to views/templates, controllers, routes, view helpers, JavaScript/Stimulus, mailers and mailer views, UI-facing i18n strings, or front-end components.
• **Not user-facing** — only models, lib, service objects, migrations with no UX effect, tests, CI config, dependency bumps, or docs.

If the diff has **no user-facing surface**, STOP. Do not generate a document. Tell the user plainly:

> No user-facing changes detected in this PR — a browser walkthrough doesn't apply. Proceed to `/code-review`.

If the change is user-facing — or a mix where the UI surface is worth exercising — continue.

3. Map flows, personas, and credentials

• From the changed views/controllers/routes, determine which screens and user journeys changed.
• Identify every user role/persona that touches the changed flows.
• Find concrete test accounts for each persona by reading the project's seed data (e.g. `db/seeds.rb`), fixtures, or factories. Use exact credentials. Reserved-example logins (`@example.com` and friends) render as click-to-copy controls in the HTML; real-looking ones become plain-text placeholders — see **Credentials in published artifacts** under Publishing.
• Determine the local login mechanism by reading the project (password, magic link via a dev mail catcher, a dev-only shortcut) and describe it literally.
• Read `CLAUDE.md` for project-specific concerns to fold in: default locale and bilingual requirements, mobile-first/viewport rules, theme, accessibility.

4. Determine setup specifics

• The command to start the app and the URL to confirm it boots.
• Whether the diff adds migrations, env vars, credentials, or dependencies the user must apply first — list them concretely, never "some changes."
• Whether seed data needs loading or a reset.

5. Generate the walkthrough document

Plan the content using the principles below, then render it as a self-contained HTML file per **Rendering the HTML artifact** (the same renderer both modes use). Principles:

• One numbered **Part** per distinct flow or persona. Cover every affected persona.
• Steps are literal and clickable — the reader should never have to guess.
• Every step or part has an explicit ✅ **expected result**, precise enough that a deviation is obvious.
• Clearly label what is **new in this PR** versus **pre-existing context** shown to complete the picture.
• Fold in locale and responsive checks when the project's guardrails call for them.
• Call out anything in the change that is **not browser-testable** (e.g. a model validation behind a constrained UI) so the reader knows it is covered only by automated tests.
• Keep it brief — this is a pre-flight check, not exhaustive QA. Favor the highest-signal paths.
• If you notice something that looks broken while writing the walkthrough, flag it to the user directly — do not bury it as a test step.

6. Render, save, and surface

• Render the content as HTML following **Rendering the HTML artifact** below. This is the pre-review scratch copy, so **omit the production-verification callout**.
• Save to the project-local `tmp/` directory — `tmp/pr-<N>-walkthrough.html` (or `tmp/<branch-slug>-walkthrough.html` if there is no PR). Not the system `/tmp`.
• This file is the orchestrator's scratch copy: not committed, not part of the PR. The PR comment posted later by `--publi