qa-handoff

name	qa-handoff
description	Update GitHub issue with testing checklist for QA testers. Use after implementation is complete, before merge. Invoke with '/qa-handoff #42 path/to/spec.md' or 'qa handoff', 'ready for testing', 'update issue for QA'.
contract	{"tags":["closure","qa","github"],"state_source":"spec","inputs":{"params":[{"name":"issue_number","required":true},{"name":"spec_path","required":true}],"gates":[]},"outputs":{"mutates":[],"side_effects":["Posts QA checklist","Sets status to QA","Links PR"]},"next":[],"human_gate":false}

QA Handoff

Posts a testing checklist to a GitHub issue so QA testers have everything they need for manual verification. This is the final step before merge.

When to Use

Use this skill when:

• Implementation is complete and verified
• PR is ready for review/merge
• QA testers need to know what to test manually
• User says "ready for testing", "qa handoff", or "update issue for QA"

Prerequisites

Before using this skill:

1. Implementation must be complete
2. Automated tests must be passing
3. /verification-before-completion should have been run
4. PR should exist (or be ready to create)

Instructions

Step 1: Gather Inputs

Require two inputs from the user:

1. Issue number (e.g., #42 or 42)
2. Spec document path (e.g., Documents/specs/42-dark-mode-spec.md)

If not provided, ask:

• "What's the issue number?"
• "Where's the spec document?"

Step 2: Read the Spec

Read the spec document to extract:

• Feature summary (from Problem Statement)
• Acceptance criteria (the testing checklist)
• Any specific test scenarios mentioned

See shared/spec-io.md for spec sections and how to extract acceptance criteria.

Step 3: Get PR Information

Check for an open PR linked to this work:

gh pr list --state open --head $(git branch --show-current)

If a PR exists, note its number. If not, note that PR creation is pending.

Step 4: Format Testing Checklist

Convert acceptance criteria to a QA-friendly format:

1. Use checkbox syntax for trackable items
2. Add context where needed (not just the criterion)
3. Include browser/device requirements if applicable
4. Note any test data needed

Example transformation:

Spec criterion:

• Toggle appears in Settings > Appearance

QA checklist item:

• Navigate to Settings > Appearance. Verify dark mode toggle is visible.

Step 5: Post to GitHub Issue

Create a comment on the issue with this structure:

## Ready for QA Testing

**Status:** Implementation complete, ready for manual verification.

**Spec:** `{spec-path}` (see repo for full details)

**PR:** #{pr-number} (or "PR pending")

---

### Manual Testing Checklist

{Converted acceptance criteria as checkboxes}

---

### Test Environment
- Branch: `{current-branch}`
- Prerequisites: {any setup needed}

### Notes for Testers
{Any additional context, known limitations, or specific things to watch for}

See shared/github-ops.md for posting the QA checklist comment.

Step 6: Link PR to Issue (if applicable)

If a PR exists and isn't already linked, update the PR to reference the issue.

See shared/github-ops.md for linking PR to issue.

Step 7: Update Project Board Status

MANDATORY: Set the issue status to QA on the project board.

See shared/github-ops.md for updating project board status.

End-of-skill check: See shared/primitive-updates.md. Signals: decisions made during QA review.

Step 8: Confirm Handoff

Tell the user:

"QA handoff complete:

• Testing checklist posted to issue #{number}
• Project board status set to QA
• PR #{pr-number} is ready for review
• QA testers can now verify the acceptance criteria

Next: Wait for QA sign-off, then merge."

Example Output

For issue #42 with a dark mode spec:

## Ready for QA Testing

**Status:** Implementation complete, ready for manual verification.

**Spec:** `Documents/specs/42-dark-mode-spec.md`

**PR:** #123

---

### Manual Testing Checklist

- [ ] Navigate to Settings > Appearance. Verify dark mode toggle is visible.
- [ ] Click the toggle. Verify the theme switches immediately without page reload.
- [ ] Refresh the page. Verify the dark mode preference persists.
- [ ] Test in Chrome and Firefox. Verify consistent behavior.
- [ ] Test with system set to light mode. Verify app respects user preference over system.

---

### Test Environment
- Branch: `feature/dark-mode`
- Prerequisites: None, works on any account

### Notes for Testers
- Toggle state is stored in localStorage, so clearing browser data will reset it.
- This does not include per-page theme customization (explicitly out of scope).

Best Practices

1. Make checklists actionable - "Verify X appears" not just "X appears"
2. Include navigation steps - "Go to Settings > Appearance" not just "In settings"
3. Note browser requirements - If testing should happen in specific browsers
4. Mention test data - If QA needs specific accounts or data to test
5. Keep it concise - Link to spec for full details, don't duplicate everything

Common Issues

No PR exists yet:

• Note "PR pending" in the comment
• Remind user to create PR and link it

Issue already has testing info:

• Add a new comment rather than editing old ones
• Reference the latest implementation state

Spec has many criteria:

• Group related criteria under subheadings
• Prioritize critical paths first