/plan-tests

name: plan-tests
model: inherit
effort: medium
agents: []
description: >
  Use to turn a feature's acceptance criteria into a test plan before any test is written — a
  table that maps every spec.md §5 acceptance criterion to at least one test, names the test
  levels (unit / integration / e2e / contract / load) without binding to a language or
  framework, and fixes the integration and data strategy. Triggers on "plan tests for {slug}",
  "test plan for {slug}", "how do we test {slug}", "test strategy for {slug}",
  "/sdd:plan-tests {slug}", "план тестів для {slug}", "як тестувати {slug}", "тест-план".
  Output: docs/features/{slug}/test-plan.md (separate file for M+), or inline in spec.md for
  XS/S per the size matrix. Hard-refuse if spec.md is missing → run `specify {slug}` first.

Skill: plan-tests

Turns an already-specified feature into a **test plan**: a table that ties every acceptance criterion in `spec.md §5` to at least one named test, the levels those tests live at (unit / integration / e2e / contract / load), the integration strategy (a real dependency, spun up throwaway), and the test-data + cleanup approach. The plan is written *before* a single test exists — the next stage, `implement`, reads this map and writes the red tests against it, not "however it seems". This file is the spine; the output scaffold lives in `templates/test-plan.md`.

This skill keeps only its own machinery. Question phrasing is **shared** → [`../_shared/ask-style.md`](../_shared/ask-style.md). Depth (inline in the spec vs a separate file) follows the **size matrix** → [`../_shared/size-matrix.md`](../_shared/size-matrix.md). It names test *levels*, never test *tools* — the concrete commands are detected by `implement` against the repo, not hard-coded here.

Plan prose follows `artifact_language` — the `## Test plan` heading (parsed downstream), test names and level tokens stay English → [`../_shared/artifact-language.md`](../_shared/artifact-language.md).

Owner

QA + the engineer who will implement the feature (co-authors). QA drives the level breakdown and the edge/error cases; the implementing engineer confirms each acceptance criterion has a reachable test and that the integration strategy fits the repo. The Tech Lead signs off that no acceptance criterion is left uncovered.

Inputs

• `<slug>` — the same feature slug every earlier stage used.
• **Gate (hard-refuse if missing):** `docs/features/<slug>/spec.md`. Its §5 acceptance criteria are the entire reason this plan exists — each one must map to a test. If `spec.md` is absent → STOP and point: «run `specify <slug>` first — the test plan maps its §5 acceptance criteria to tests».
• (Optional) `docs/features/<slug>/data-model.md` — the entity shapes tell you what test data to build and what to seed/clean per suite. Read it if present.
• (Optional) `docs/features/<slug>/sad.md` §6 sequence diagrams — each drawn flow is an e2e candidate; each cross-participant boundary is a contract-test candidate.
• (Optional) `docs/features/<slug>/.size` — depth hint. Absent → default to M (separate `test-plan.md` file) **and say so loudly in the handoff** — «size M (default — no `.size`; run `/sdd:classify-size <slug>`)».

Protocol

1. **Gate.** `test -f docs/features/<slug>/spec.md` → fail = refuse with the pointer above. Then read §5 (acceptance criteria — the rows of the coverage table) and §6 (NFRs — which drive load tests). Read `data-model.md` / `sad.md` §6 if present. 2. **Pick the output target.** Per the size matrix: **XS/S → write the plan inline in `spec.md`** as a short `## Test plan` section (a coverage table is enough — no separate file); **M+ → a separate `docs/features/<slug>/test-plan.md`** from the template. Confirm the target with one `AskUserQuestion` (phrasing per [`../_shared/ask-style.md`](../_shared/ask-style.md)) when `.size` is absent. Then **bootstrap the target**: copy the template to `test-plan.md` (M+), or add the empty `## Test plan` section to `spec.md` (XS/S) — every row from here on lands in that file as it is decided → [`../_shared/write-and-commit.md`](../_shared/write-and-commit.md). 3. **Map levels — generic only.** Name test levels from a fixed vocabulary, never a tool or language: **unit** (pure logic — a rule, a calculation, a validator, no I/O), **integration** (the module against a real dependency it owns — DB, cache, queue), **e2e** (a full flow end to end, one per critical user story), **contract** (a boundary between two participants — an API shape or an event schema agreed by both sides), **load** (only when an NFR carries a number — throughput, p95 latency). **When `sad.md` frontmatter `target_surfaces` declares a UI surface** (`web-frontend` / `mobile-app` / `desktop-app`), add the frontend tiers — **component** (a UI component exercised in isolation), **visual-regression** (web — the rendered UI diffed against a baseline), **e2e-through-UI** (the flow driven through the real UI, not just the API). These are the **"testing trophy"**, the dominant frontend testing vocabulary (web.dev / Kent C. Dodds) — a vocabulary, not a mandate (→ [`../_shared/surfaces.md`](../_shared/surfaces.md)). When the design pipeline ran, source the UI rows from its artifacts: the **e2e-through-UI path comes from `ux-flows.md`** (the flow is the test's script) and the **states a component test must cover come from `screens.md`** (the manifest's state rows). Do not write tool names (no specific test runner, broker, visual-regression, or load tool) — `implement` detects what the repo already uses (e.g. Playwright / Storybook / a visual-diff tool). 4. **Core mapping (the contract of this skill) — user chooses the level per AC.** Build the AC→test table: **every acceptance criterion in §5 maps to ≥1 test.** For each AC, **propose a default level** from a heuristic (pure logic/rule/validator → unit; behaviour against a real dependency the module owns → integration; a full user-story flow → e2e; a cross-participant API/even