Walkthrough

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 --publish is the published snapshot.
• Open it for the user (open tmp/pr-<N>-walkthrough.html) and tell them the path.

7. Recommend the next step

Exercise the walkthrough in the browser. If anything is off, fix it on the branch and re-run /walkthrough to refresh. When it looks right, proceed to /code-review — then publish the final version with /walkthrough --publish before merge.

Rendering the HTML artifact

Both modes render the walkthrough as a single self-contained HTML file using this skill's template.html and the shared house style. Same renderer; the only differences are called out inline.

• Read template.html (this skill's directory) for the structure and ../_shared/house-style.html for the look.
• Inline the shared house style — copy its <style> block in place of the first HOUSE STYLE marker in <head>, and its <script> block in place of the second marker before </body>. The output must be a single self-contained .html (no external assets).
• Strip every instructional comment from the output (the head how-to block and the body notes). The artifact must be clean — HTML comments don't nest, so a stray instructional comment can break rendering.
• Fill the metadata tokens: {{PROJECT}}, {{PR}}, {{PR_LINK}} (link to the PR), {{FEATURE}} (short feature name), {{BRANCH}}, {{COMMIT}} (short SHA), {{DATE}}, {{ESTIMATE}}. Before a PR exists, use the branch name and point {{PR_LINK}} at the branch.
• Launch-status callout (lifecycle-gated): for the default pre-review scratch copy, omit the entire .callout block. For the --publish (post-merge) version, determine the project's launch status from its CLAUDE.md § "QA Testing Policy" (the Launch status: flag), then include the matching .callout:
  • Pre-launch, or no QA Testing Policy is declared → the production-verification callout (testers without a local environment may verify on the live site; its data is disposable). This is the template's default .callout.
  • Post-launch → the local-dev-only callout instead: a warning that QA must run on a local dev checkout and must not be run against the live site, which holds real data. Emit no "verify on production" text. (See the template's comment for both snippets.)
• Every command, URL, and reserved-example login the reader will paste is a <button type="button" class="copy" data-copy="VALUE">VALUE</button> control (see Credentials in published artifacts). Only real/non-example credentials are the exception — render those as plain <code>&lt;your-admin-email&gt;</code>, never a copy control.

Reliable way to inline the bulky house style without hand-copying it: write the filled template with two sentinel lines where the markers sit, then splice the <style> and <script> blocks out of house-style.html into them with a short script. Extract by the exact tags (<style> … </style>, <script> … </script>) — house-style.html keeps its instructional comment tag-free precisely so this match is unambiguous.

• Verify before surfacing the artifact. The finished HTML must contain exactly one <style> and one <script>, with no instructional text leaked into the <head>. Grep the output for Inline the, Component vocabulary, EXTRACTION GUARDRAIL, or a stray --> before the first :root — any hit means a comment was captured instead of the real block. Re-extract by the exact tags and re-check. This has bitten us before; do not skip it.