add-qa-spec

name	add-qa-spec
description	Generate a code-free QA/E2E specification (reachability intent, UX acceptance criteria, functional E2E scenarios, capture states, target viewports, a11y expectations) from about.md + design.md + plan-*.md, and author the _tests/screens.json screen catalog by read-merge-write. Loaded by add.plan's qa-pipeline QA-Spec step.

QA/E2E Specification — Case Generation Rubric

LANG: Respond in user's native language. Tech terms in English.

When to Use

• add.plan's qa-pipeline-gated QA-Spec step (STEP 10.0), to produce plan-qa-spec.md AND author _tests/screens.json before consolidation.

When NOT to Use

• Contract test cases (input/output pairs from RFs/RNs) — that's add-test-specification.
• Judging/scoring an implementation against a rubric — that's add-qa.

Inputs

• about.md — RF/RN + acceptance criteria.
• design.md — UX contract (layout/hierarchy/spacing/tokens/state). Resolve it per the feature-design Location rule in {{skill:add-doc-schemas/references/new-feature.md}} (SF-level first, feature-level fallback).
• Area plan-*.md (plan-database.md, plan-backend.md, plan-frontend.md) — technical contracts, if they exist.
• FEATURE_DIR/_tests/screens.json — the existing catalog (scaffolded by add.qa-setup, or written by a previous plan run). Absent on a first run.
• docs/qa/config.json — default viewport set (required to resolve the viewports column).

QA/E2E Case Generation

Emit one row per surface/subfeature that design.md declares — never skip a declared screen (the run's coverage gate treats a declared-but-unspecced screen as a blocker). Per surface, derive:

• Reachability intent — route (path) OR non-route open-recipe intent (e.g. "opened via the New-entry button on /entries"). Record the intent only — real selectors are finalized post-implementation by @e2e-agent, which merges this intent with the rendered DOM. You DO write the intent into screens.json (see Screen Catalog below); you do NOT invent selectors.
• UX acceptance criteria — tied to design.md (layout/hierarchy/spacing/tokens/state).
• Functional E2E scenarios — given/when/then per acceptance criterion. CRUD heuristic: when a surface manages a data entity (a form that persists, or a listing), enumerate create / read / update / delete / list as distinct scenarios. Where about.md has no acceptance criterion for an operation, still list it and mark the row a gap — never invent the criterion.
• Capture states — the UI states to screenshot for the surface, from the canonical vocabulary: default, empty, filled, submitted, list, detail, created, updated, deleted, error, success. A data-entity surface typically yields empty,filled,list. A single-state surface uses default. These map 1:1 to the screenshot files <screen>.<state>.<viewport>.png.
• Target viewports — default from docs/qa/config.json; per-surface override when the design demands it.
• a11y expectations — which surfaces carry explicit a11y acceptance (labels, focus trap, contrast, keyboard nav, etc.).

Output 1 — plan-qa-spec.md

Write to docs/features/${FEATURE_ID}/plan-qa-spec.md under a ## QA/E2E Specification heading:

ID	surface	SF	reachability	viewports	capture states	UX acceptance	functional scenario	a11y
QA01	entry-form	SF01	modal (open via New-entry)	mobile,desktop	empty,filled,list	fields render + width rule	submit persists entry + list shows it	labels + focus trap

Output 2 — Screen Catalog (_tests/screens.json)

You OWN this file when dispatched by add.plan STEP 10.0. (add.qa-setup STEP 8 only scaffolds it at setup time, before any plan exists.) One catalog entry per row of the table above.

Entry shape

{
  "feature": "<feature-id>",
  "screens": [
    { "id": "login", "sf": "SF02", "name": "Login", "kind": "route",
      "path": "/login", "auth": false,
      "design": "docs/features/<id>-.../subfeatures/SF02-.../design.md",
      "expect": "what a correct render looks like" },
    { "id": "entry-form", "sf": "SF01", "name": "Entry form", "kind": "modal",
      "open": [{ "goto": "/entries" }, { "click": "role=button[name=New entry]" }],
      "auth": true,
      "design": "docs/features/<id>-.../subfeatures/SF01-.../design.md",
      "expect": "modal open with all fields visible" }
  ]
}

Field	Rule
id	stable kebab surface id — matches the surface column of your table
sf	the subfeature the surface belongs to (SF01, …); the merge key together with id
name	human label
kind	route | modal | overlay | portal
path	route surfaces only
open	non-route surfaces only — ordered recipe, each step exactly one of {"goto":"<path>"}, {"click":"<selector>"}, {"fill":["<selector>","<value>"]}, {"select":["<selector>","<value>"]}, {"wait":"<selector | ms>"}. Playwright role/testid syntax — never brittle CSS
auth	true when the surface requires an authenticated session
design	the design.md path actually used for that screen (SF-level when it exists, feature-level fallback)
expect	one line describing a correct render — derived from the screen's ## Design Contract rows (Dimension/Declares) plus its layout tree, never freehand

Route surfaces keep path; non-route surfaces declare kind + open. Both forms coexist in one catalog.

Read-merge-write (MANDATORY)

The catalog is feature-wide while a plan run is scoped to one SF — so it is NEVER rewritten from scratch. Merge by sf + id:

1. Read the existing file. Absent → start from {"feature":"<feature-id>","screens":[]}.
2. Entries whose sf is OUT of this run's scope are preserved byte-identically — never reorder, reformat, or "clean up" them.
3. An in-scope entry (same sf AND same id) is replaced by the newly derived one.
4. A newly derived in-scope entry with no match is appended.
5. An in-scope entry whose screen no longer exists in the consolidated design.md is removed (out-of-scope entries stay untouchable — rule 2 above).

Store reachability INTENT only. If a design doc is missing or thin, list the screen with a note rather than inventing a route — flag it as a gap for the user.

Rules

• Code-free only — no implementation code, no test scripts. The screens.json open recipe is reachability intent, not a test: never hand-write selectors you have not observed; @e2e-agent finalizes them post-implementation.
• Keep plan-qa-spec.md under ~15 lines (tabular). screens.json has no line budget — it carries one entry per declared screen.
• Flag missing UX acceptance / thin design as gaps — never invent content.
• Each row maps to one surface/subfeature; do not merge unrelated surfaces into one row.
• Emit a row for every screen design.md declares — an omitted declared screen becomes a coverage blocker at run time.
• capture states uses the canonical vocabulary only; single-state screens use default. Do not invent a passing CRUD scenario for an operation about.md does not cover — mark it a gap.
• Every plan-qa-spec.md row has a matching screens.json entry (same sf + id) and vice versa for in-scope surfaces — the two outputs are one specification in two shapes.
• NEVER rewrite screens.json wholesale — out-of-scope SF entries survive byte-identically.
• expect is never freehand: derive it from the screen's ## Design Contract rows (what it declares per dimension) and its layout tree, both in design.md — a screen whose design.md carries no contract or layout tree gets a gap note instead of an invented expect line.