qa-plan

name	qa-plan
description	Generate a QA test plan for a sprint or feature. Reads PRDs and stories, classifies stories by test type (Logic/Integration/Visual/UI/Config), and produces a plan covering automated tests, manual cases, smoke scope, device matrix, and sign-off rules. Run before sprint kickoff or when starting a major feature.
argument-hint	[sprint-id | feature: <name>]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Edit, AskUserQuestion
model	sonnet
agent	qa-lead

QA Plan

The contract that says: for this scope, here is what will be tested, how, on which devices, and what defines done. Authored once at sprint start and referenced by every QA action that follows.

---

Phase 1: Resolve the Scope

Parse the argument:

• sprint-NN -> read production/sprints/sprint-NN/ and every story inside.
• feature: <name> -> glob stories tagged for that feature/system.
• No argument -> read production/session-state/active.md for the current sprint, or ask the user.

Read each story file fully — title, ID, layer, type, acceptance criteria, dependencies.

Read related PRDs from design/prd/ to understand the feature context.

Confirm scope and story count with the user.

---

Phase 2: Classify Each Story

For every story, assign a Test Type:

• Logic — pure functions, formulas, state machines, validation, pricing math.
• Integration — multi-module flows (e.g., sign-up triggers email triggers analytics event).
• Visual/Feel — animation, motion, haptics, transitions.
• UI — screens, navigation, forms, lists.
• Config/Data — pricing, feature flags, remote config, copy.

The default mapping when ambiguous:

• Story touches a screen file -> UI.
• Story touches an animation/motion module -> Visual/Feel.
• Story changes pricing/copy/flags only -> Config/Data.
• Story implements a calculation or validator -> Logic.
• Story crosses two modules with side effects -> Integration.

Surface ambiguous classifications via AskUserQuestion before continuing.

---

Phase 3: Determine Required Evidence

Per Type, the evidence requirement:

Type	Required evidence	Location
Logic	Unit test, must pass in CI	tests/unit/[module]/
Integration	Integration test or documented manual flow	tests/integration/[module]/
Visual/Feel	Screenshot or screen recording + lead sign-off	production/qa/evidence/
UI	Walkthrough doc OR Detox/Maestro/XCUITest/Espresso flow	production/qa/evidence/ or tests/e2e/
Config/Data	Smoke check pass	production/qa/smoke-[date].md

For each story, write its required Test Evidence path back into the story file under Test Evidence:. Ask before each edit.

---

Phase 4: Define the Device Matrix

Read .claude/docs/technical-preferences.md for Target Platforms. Propose a tiered device matrix via AskUserQuestion:

• Tier A — must pass before any release (representative low-end + high-end per platform).
• Tier B — covered weekly during the sprint.
• Tier C — covered before milestone gates only.

Defaults if not configured:

• iOS Tier A: latest iPhone, an iPhone two generations old, latest iPad.
• iOS Tier B: an iPhone SE-class small screen, last iOS minor version.
• Android Tier A: a flagship Pixel, a representative mid-range, the oldest supported Android version.
• Android Tier B: a low-RAM device, a tablet.

Capture the matrix in the plan.

---

Phase 5: Smoke Scope

List the critical paths that the smoke check must cover. Default seeds:

• Cold start within budget.
• Sign-in or guest entry succeeds.
• Primary CTA on home reaches its destination without crashing.
• Sign-out succeeds.
• Push notification received in foreground does not crash.
• Deep link from a known URL opens the right screen.

Add any sprint-specific smoke flows (e.g., "new paywall opens and purchase test card succeeds").

---

Phase 6: Manual QA Sessions

Estimate effort per Visual/Feel and UI story. Default 30 minutes per UI story, 45 minutes per Visual/Feel story, plus 1 hour for cross-device parity.

Render an Effort table:

Story	Type	Effort	Tester	Devices

Surface total manual hours and ask the user whether the sprint has the capacity.

---

Phase 7: Compose the Plan Document

# QA Plan — [Sprint / Feature]

Author: qa-lead
Date: [date]
Scope: [N] stories
Status: Proposed

## Story Classification
| Story | Type | Evidence Path |

## Automated Test Requirements
- Logic stories needing unit tests: [list]
- Integration stories needing integration tests: [list]

## Manual QA Scope
| Story | Devices | Steps overview | Effort |

## Smoke Scope
[bulleted critical paths]

## Device Matrix
- Tier A: [list]
- Tier B: [list]
- Tier C: [list]

## Out of Scope
[explicit list — what is NOT being tested this cycle and why]

## Entry Criteria
- Smoke check PASS
- All Logic story tests are green in CI
- Build is signed and installable on Tier A devices

## Exit Criteria
- All in-scope stories closed (PASS or FAIL with bug filed)
- No S1 or S2 bugs open
- Test evidence in place per the table above

## Sign-Off
- QA Lead: [name]
- Producer: [name]

---

Phase 8: Save and Update Stories

Ask before each write:

• Write the plan to production/qa/qa-plan-[sprint]-[date].md.
• For each story, edit the Test Evidence: field to match the table.

Append to production/session-state/active.md:

## QA Plan Created — [date]
- Plan: [path]
- Stories in scope: [N]
- Smoke scope: [N flows]
- Device matrix: [Tier A counts]

---

Quality Gates / PASS-FAIL

• PASS — every story has a Type, required evidence path, and an estimated effort. Smoke scope and device matrix are non-empty.
• FAIL — any story is unclassified or missing an evidence path. Resolve before proceeding.

---

Examples

Example 1 — Sprint 4 plan: Scopes 11 stories. Classifies 5 Logic, 3 Integration, 2 UI, 1 Config. Surface 1 ambiguous story to user, who reclassifies it Integration. Writes plan, updates 11 stories. Total manual hours: 6.5.

Example 2 — Feature plan for "Push Notifications": Scopes 4 stories. 2 Integration (server push -> device delivery), 1 UI (notification settings screen), 1 Config (Firebase project ID swap). Smoke flow added for foreground/background delivery.

---

Next Steps

• Run /test-evidence-review mid-sprint to verify evidence is materializing.
• Run /team-qa sprint-NN at sprint end to execute the cycle.