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.