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.