H Test Handoff

---
description: Generate a QA-team handoff document from a code change or bug fix — covers reproduction, impact scope, recommended test scope, rollback, and open questions.
argument-hint: [slug] [--bug-fix] [--commits <range>] [--branch <name>] [--ticket <ref>]
---

Produce a structured handoff document for the QA / test team based on a code change or bug fix that is **already complete** (compile + tests pass on the developer side). The document gives QA enough context to design test cases without re-reading the diff line-by-line.

**Distinction:**
- `/h-pr` produces a PR description for code reviewers (focus: what + why).
- `/h-test-handoff` produces a QA briefing (focus: how to verify + what to test + what to skip).

Both can be run on the same change; they answer different questions.

## Step 1 — Parse `$ARGUMENTS`

- `[slug]` (optional): the task slug. If omitted, derive from the active `task_brief.md` in `.claude/runs/task-briefs/` or from the current git branch name.
- `--bug-fix` (optional): forces the bug-fix template (different sections — see Step 5b). If omitted, auto-detect: presence of an incident file at `.claude/wiki/incidents/*<slug>*.md` OR a launch_spec row prefixed `fix-` → bug-fix mode; otherwise feature-change mode.
- `--commits <range>` (optional): explicit git commit range (e.g. `main..HEAD` or `abc123..def456`). Default: `$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main)..HEAD`.
- `--branch <name>` (optional): override branch name in the report. Default: `$(git branch --show-current)`.
- `--ticket <ref>` (optional): ticket reference (GitHub issue #, Jira key, Linear ID) to link from the handoff. If a task_brief frontmatter already has `ticket_ref` / `ticket_url`, prefer those.

## Step 2 — Locate the source artifacts (manual workflows are first-class)

The user **may have worked manually** (edited code directly, no `/h-fix-bug` / `/h-brief` run). Do NOT assume a task_brief or incident file exists. The command must work whether the change came from our pipeline OR from raw manual editing.

Probe in this order, **collect every hit** (do not stop early — multiple sources combine):

1. Active `task_brief.md`: `ls .claude/runs/task-briefs/*<slug>*_task_brief.md` (1 match expected). Read Machine Section if present.
2. Archived `task_brief.md`: `ls .claude/wiki/archive/*<slug>*_task_brief.md`. Read.
3. Incident file (bug-fix mode): `ls .claude/wiki/incidents/*<slug>*.md`. Read.
4. PR description: `gh pr view --json title,body 2>/dev/null` (if `gh` available and PR exists).
5. **Commit messages** (always — even when 1-4 hit): `git log --pretty=format:"%h%n%an %ad%n%s%n%b%n---" <commits>` — full subject + body. Commit body often contains rationale that no other artifact captured.
6. **Uncommitted working tree** (always — for in-progress local edits): `git status --porcelain` + `git diff HEAD` + `git diff --cached`. If non-empty, the change set extends BEYOND `--commits <range>` — treat working-tree edits as part of the change for this handoff.

If steps 1-4 all miss AND only steps 5-6 yield signal → mark mode as `manual-workflow` in the report. This is a normal scenario, not an error.

**Source-of-truth ordering when sources conflict:**
1. Uncommitted working tree (most recent intent)
2. Local commits in `<range>`
3. task_brief / incident / PR descriptions
4. User answers from Step 2.5 below

A later layer overrides earlier — i.e. if working-tree changes contradict the task_brief, trust the working tree and flag the divergence in `[Sections with author-confirmed gaps]` of the final report.

## Step 2.5 — Clarification loop (BEFORE drafting)

**When content or boundary is unclear, ask the user — do NOT guess, do NOT pre-fill placeholders.**

After gathering all sources from Step 2, run a mental checklist of the QA-doc sections (see Step 5). For any section where the gathered signal is thin (no clear answer derivable from sources), **ask the human via `AskUserQuestion` and wait**. Repeat until either:

- Every required section has answerable signal, OR
- The user explicitly waives a section ("skip §6 What NOT to Test" → write `_Not applicable — confirmed by author._`), OR
- 5 question-rounds elapsed (anti-loop cap — STOP and emit `[Status]: ESCALATE` with the remaining gaps)

Typical clarifications to ask (only the ones actually unclear — don't ask everything):

| Section | When unclear | Question to ask |
|---|---|---|
| §1 Change Summary | Commit messages cryptic, no task_brief | "Describe in one paragraph what changed for the end user — business outcome, not code." |
| §2 Affected Surfaces — HTTP/DB | Diff touches a class but the public surface is ambiguous | "Does this change alter any HTTP endpoint response shape, status code, or DB table/column? Name them if yes." |
| §3 How to Verify | No ACs in any source | "Give me 1-3 concrete scenarios I can convert to test cases — Given/When/Then format if possible." |
| §3 (bug-fix) Reproduce ORIGINAL bug | No incident file, no repro in commit body | "What were the exact steps to reproduce the bug before this fix? Environment, inputs, expected vs actual." |
| §4 Edge Cases | Happy path clear, edges absent | "Any edge cases or negative inputs the fix should handle? (invalid input / empty / max / concurrent)" |
| §6 What NOT to Test | Scope boundary unclear | "What parts of the system are explicitly NOT affected by this change? QA should skip those." |
| §7 Environment | Config / migration touched but no setup instructions | "What does QA need in their env? (apply migration X, set feature flag Y, seed data Z)" |
| §8 Rollback | HIGH risk or DB migration without rollback notes | "How do we roll back if this regresses? (revert commit / flag flip / rollback script)" |

After every answer batch, re-evaluate the section list. Continue until covered.

**Hard rule:** writing `_None observed_` for a section is only allowed AFTER asking the user about it and the user explicitly waived. Otherwise, ASK.

## Step 3 —