qa-plan skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys automation,workflow,qa.level,systemoverrides

Resolved above — use as-is. No block → defaults in .claude/docs/config-resolution.md.

QA Plan

This skill generates a structured QA plan for a sprint, feature, or individual story. It reads all in-scope story files and their referenced GDDs, classifies each story by test type, and produces a plan that tells developers exactly what to automate, what to verify manually, what the smoke test scope is, and when to bring in a playtester.

Run this before a sprint begins so the team knows upfront what testing work is required. A test plan written after implementation is a post-mortem, not a plan.

Output: production/qa/qa-plan-[sprint-slug]-[date].md

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

Workflow tier: resolve per the GDD's system as each is read (per .claude/docs/workflow-modes.md): workflowoverrides.systemoverrides. if the block lists one, else the project value. It sets how many GDD sections the test plan is mined from — see Phase 2.

qa.level: at minimal, produce only a minimal smoke plan — drop the automated-test-required rows and the test-file DoD; at standard, a full plan per story type; at full, also add per-system coverage targets. Distinct axis from workflow (which sets how many GDD sections are mined).

Phase 1: Parse Scope

Argument: $ARGUMENTS (blank = ask user via AskUserQuestion)

Determine scope from the argument:

every story file path referenced. If production/sprint-status.yaml exists, use it as the primary story list and fall back to the sprint plan for story metadata.

• sprint — read the most recent file in production/sprints/, extract

to stories whose file path or title contains the system name. Also check the epic index file (EPIC.md) in that system's directory.

• feature: [system-name] — glob production/epics//story-.md, filter

"Specific story (enter path)", "Full epic"

• story: [path] — validate that the path exists and load that single file.
• No argument — use AskUserQuestion:
• "What is the scope for this QA plan?"
• Options: "Current sprint", "Specific feature (enter system name)",

After resolving scope, report: "Building QA plan for [N] stories in [scope]."

If a story file path is referenced but the file does not exist, note it as MISSING and continue with the remaining stories. Do not fail the entire plan for one missing file.

If the resolved scope contains ZERO stories, stop — do not build a plan.

Report NOT ASSESSED — no stories in scope, naming which scope was searched

and which path was empty, and route:

- no file in production/sprints/ → "No sprint plan found. Run /sprint-plan new."

- a sprint plan exists but references no stories → "Sprint plan [path] lists no

stories. Run /create-stories [epic-slug]."

- feature:/story: scope matched nothing → name the glob that came back empty.

The N=0 guard is mandatory. Without it an empty scope reports "Building QA

plan for 0 stories" and continues into Phase 4, producing a plan document with

empty tables — and **a QA plan for zero stories looks exactly like a completed

QA plan.** This skill gates the hand-off to manual QA, so a false-clean here

sends a build to QA on the strength of a plan that tested nothing.

Note the shape, because this skill already had the harder half of the rule.

Phase 2 states "Never treat an absent section as an absent story" — the

sophisticated inner case, correctly handled. The outer boundary, no stories at

all, had nothing. The same shape appears in /story-readiness, where NOT ASSESSED

existed for per-story failures and the empty scope could not reach it.

The rule at the top of this block still stands: one missing file among several

is MISSING-and-continue. This is the different case where there is no several.

Phase 2: Load Inputs

Establish the denominator first — glob the in-scope story files and count N — then collect the fields below with targeted section greps, not a full read of each story. A QA plan needs each story's type and acceptance criteria; it does not need its implementation notes, out-of-scope boundaries or ADR rationale, and reading N stories whole to reach two sections is where this phase's cost lives:

Grep pattern="^## Acceptance Criteria" glob="production/epics/**/story-*.md" output_mode="content" -A 15
Grep pattern="^> \*\*(Type|Status|Estimate)\*\*" glob="production/epics/**/story-*.md" output_mode="content"
Grep pattern="^## (Context|Dependencies)" glob="production/epics/**/story-*.md" output_mode="content" -A 8

(Scope the globs to the sprint plan's story paths in sprint mode.) From those:

test plan actually turns on them; full-read those individual stories

• Story title and story ID — from the file name and path; no read at all
• Story Type field — from the header grep (e.g., Type: Logic)
• Acceptance criteria — the complete numbered/bulleted list, from the first grep
• GDD / ADR reference and Dependencies — from the ## Context grep
• Estimate — from the header grep if present
• Implementation files and Engine notes — only needed for stories whose

Never treat an absent section as an absent story. If a story matched no ## Acceptance Criteria, full-read that one and say so — a story with no testable criteria is a QA finding in its own right, not a story to skip.

After reading stories, load supporting context once (not per story):

GDDs are approved

• design/gdd/systems-index.md — to understand system priorities and which

system's workflow tier (resolved above) — at full, mine all 8 sections; at standard, mine the test-relevant subset of the required sections (Acceptance Criteria and Edge Cases always, plus Formulas for any system that defines numeric rules); at minimal, Acceptance Criteria only. Do not load the full GDD text. These sections contain the testable requirements, the math to verify, and the boundary conditions tests must cover. If an Edge Cases section is absent (or not expected at minimal), note per GDD: "No Edge Cases section found — edge case coverage will be inferred from acceptance criteria only."

• For each unique GDD referenced across all stories: mine test material per that

automated tests should guard against (if the file exists)

• docs/architecture/control-manifest.md — scan for forbidden patterns that

If no GDD is referenced in a story, note it as a gap but do not block the plan. The story will be classified using acceptance criteria alone.

Phase 3: Classify Each Story

For each story, assign a Story Type:

• If the story already has a Type: field in its header: accept it as-is. Do NOT re-classify or validate against the criteria below — the Type was set by lead-programmer at story creation and is authoritative. Record it as-is.
• If the Type: field is missing: infer the type from the acceptance criteria using the table below, and note in the report that the type was inferred (not declared). Flag this as a gap — the story should have its Type declared explicitly before implementation begins.

Mixed stories (e.g., a story that adds both a formula and a UI display): assign the primary type based on which acceptance criteria carry the highest implementation risk, and note the secondary type. Mixed Logic+Integration or Visual+UI combinations are the most common.

After classifying all stories, produce a classification summary table in conversation before proceeding to Phase 4. This gives the user visibility into how tests will be allocated.

Phase 4: Generate Test Plan