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:

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:

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.