/qa-handoff

name: qa-handoff
description: Generate a hands-on QA testing guide as a self-contained HTML page — for Rails apps or static (Hugo) sites. --publish uploads the HTML to the project's configured QA host.
disable-model-invocation: true
argument-hint: "[--publish] [--pr <N>]"

QA Handoff

You are a senior developer preparing a hands-on testing guide for a QA colleague. Your colleague understands the product but is NOT tracking implementation details, architecture decisions, or code-level rationale. Write for someone who needs a clear, step-by-step guide to exercise the new work and find gaps in behavior and UX.

Step 0: Detect the project type

Pick the mode from what's in the repo:

• **Rails app** — a `Gemfile` plus `config/application.rb` or `bin/rails`. Follow the **Rails path** (template `template.html`).
• **Static site (Hugo)** — a Hugo config (`hugo.toml` / `hugo.yaml` / `hugo.json`, or `config.toml` / `config/_default/`) with a `content/` directory (or another static-site generator). Follow the **Static-site path** (template `template-static.html`).
• **Neither** — tell the user this skill targets Rails apps and static sites, and stop.

Both paths produce the same kind of artifact — a single self-contained HTML page built from the shared house style and shipped through the shared publish pipeline. They differ only in which template and section content they use.

**Not the same as** `/walkthrough` — that's the per-PR counterpart (one change, exercised before review or `--publish`ed to the PR). This is the broad, committed QA guide for a whole phase.

Context

**Both paths:** Read the project's `CLAUDE.md` (project name, any audience/viewport guidance, the `## QA Publish Target` block) and `docs/prd/ROADMAP.md` if present (current phase). Check `docs/debriefs/full/` for the most recent debrief; if one covers the current work, reuse its Product Tour as the basis for the walkthrough (strip rationale, keep the actions and expected behaviors). Otherwise build the walkthrough from recent git history.

**Rails path also:** Read `db/seeds.rb` to identify test accounts and credentials (reference them exactly). Review the `Gemfile` and recent migrations for setup the tester needs.

**Static-site path also:** Identify the **deploy-preview URL** the tester should open — a Netlify deploy preview is the typical source; if it isn't obvious from `CLAUDE.md` or the repo, ask the user. Note the local preview command (`hugo server`) and whether the preview is access-gated. Check the Hugo config for **multiple languages** (`languages` / `defaultContentLanguage`, an `i18n/` dir, or `content/<lang>/`) — if multilingual, include the Languages & Translations section. Identify **forms and external integrations** and their backends (Netlify Forms, an external API, a separate app), and note any restricted to certain domains (e.g. a CORS allowlist) so the guide can tell testers which environment to use. For URL continuity, remember Hugo migrations often preserve old paths by slug-matching rather than redirect maps — check both that preserved URLs still resolve and that removed URLs are intentionally gone.

Output Format

Render the handoff as a single self-contained **HTML** page using the shared house style — not a Markdown document. Use the template for your mode:

• **Rails:** `template.html`
• **Static site:** `template-static.html`

Rendering

1. **Read your mode's template** (this skill's directory) for the structure and `../_shared/house-style.html` for the look. The template's head comment documents every token. 2. **Inline the shared house style** — copy its `<style>` block in place of the `<!-- 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). Do not link a stylesheet. 3. **Strip every instructional comment** from the output (the head how-to block and the body notes). The artifact must be clean. (HTML comments do not nest, so a leftover one can break rendering, not just clutter it.) _Static template only:_ delete any optional section that doesn't apply — the **Languages & Translations** section for a single-language site, and the **Key Flows & Forms** section for a purely informational site — along with its TOC entry. 4. **Resolve the QA report URL (`{{REPORT_URL}}`).** Find the project's GitHub repo via `gh repo view --json nameWithOwner --jq .nameWithOwner`. Look in `.github/ISSUE_TEMPLATE/` for a QA template (filename matching `qa`, case-insensitive — prefer YAML issue forms over plain Markdown). Build the URL:

• **QA template found:** `https://github.com/<owner>/<repo>/issues/new?template=<filename>`. Leave the title blank so the template's own placeholder guides the tester.
• **No QA template:** `https://github.com/<owner>/<repo>/issues/new`.
• **No GitHub remote:** omit the CTA. Replace the Feedback section's button paragraph with a one-line note pointing at the project's actual tracker.

5. **Fill the metadata tokens:** `{{PROJECT}}`, `{{TITLE}}` (e.g. `Phase N: Phase Title`), `{{DATE}}`, `{{BRANCH}}`, `{{COMMIT}}` (short SHA from `HEAD`), `{{REPORT_URL}}` (step 4); then the mode-specific one — Rails: `{{DEBRIEF_REF}}` (path to the related debrief, or `N/A`); static: `{{PREVIEW_URL}}` (the deploy-preview URL). 6. **Make every real command and URL the tester will paste a click-to-copy control:** `<button type="button" class="copy" data-copy="VALUE">VALUE</button>`.

**Credentials.** The handoff HTML is a single file that is both committed and (with `--publish`) uploaded to a public QA host. A login may be a click-to-copy control only when it is a _reserved, non-routable example identity_: an RFC 2606 reserved domain (`example.com`/`.net`/`.org`) or the `.example` TLD, with any password an obviously-fake seed value (e.g. `password`). Such fakes are documentation, not credentials. Any real or real-looking login (real domain, actu