QA Handoff

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 --published 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, actual person, live tenant, real password/token) must be a plain placeholder (<code>&lt;your-admin-email&gt;</code>), never a copy control; add a one-line note (Rails local: seeded logins from db/seeds.rb; production: your own account). Static sites usually have no logins at all — but if the deploy preview is password-gated, treat that access the same way: a placeholder plus a one-line note, never a real secret. Never publish a real secret in any form.

Section content — Rails path

Fill each token with the content below.

What's New ({{WHATS_NEW}}) — a plain-language summary of what was built. 2–4 short paragraphs; connect to the roadmap. No file paths, class names, or architecture jargon.

Getting Current ({{SETUP}}) — exact setup steps, each command a copy control: pull/install (git pull, bundle install, bin/rails db:migrate, bin/rails db:seed), whether a full bin/rails db:reset is needed, new gems/system packages, new env vars or credentials, and the command to start the app plus the URL to confirm it boots. List specifics — never "some dependencies changed." Say "None" where a category is unchanged.

Guided Walkthrough ({{WALKTHROUGH}}) — one <div class="story"> per scenario, in order. Each: a descriptive .story-head with a .role-pill for the user type; a click-to-copy login when it is a reserved-example identity, otherwise a placeholder (see Credentials), plus a copyable starting URL; extremely literal numbered steps; and a .expect expected result precise enough that a deviation is obvious. Include at least one scenario per affected role. Read CLAUDE.md for audience/viewport guidance and add matching scenarios.

Exploratory Testing ({{EXPLORATORY}}) — an interactive <ul class="checklist">; each item <li><label><input type="checkbox" data-check="..."> ...</label></li>. Draw from debrief-flagged thin coverage, permission boundaries (accessing another user's data, role escalation), responsive/mobile checks, and edge cases a developer might skip. Make each item self-describing.

Test Suite ({{TESTS}}) — commands to run the full suite and the targeted files most relevant to the new work, each a copy control. Note any known skips or expected failures.

Feedback — built into the template: a CTA button linking to the QA issue form via {{REPORT_URL}}. Do not reconstruct the form.