| name | qa-author-by-us |
| description | QA-Author by-us mode procedure. Use when QA-Author is dispatched after SRS sign-off to author User Story scoped functional test cases under docs/test-cases/by-us/<US-ID>/, create executable spec scaffolding, perform Pass 1 selector TODO marking, or perform Pass 2 selector backfill from docs/instrumentation-contract.md. |
| agents | ["qa-author"] |
| sdlc_phase | qa |
| owner | Platform Eng |
| status | active |
QA Author By-US
Use
Use this skill for QA-Author by-us mode. Load test-case-author first for TC format and coverage rules, then ui-test-execution for executable spec conventions.
Inputs
- Signed-off
docs/SRS.md
- Per-US files at
docs/user-stories/<US-ID>.md
- Linked FR files as needed
- Optional scope filter of US IDs
- Pass number:
1 or 2
Pass 1 Procedure
- For each in-scope US, read its Description, Main Flow, Business Rules, Post-conditions, and Acceptance Scenarios.
- Write
docs/test-cases/by-us/<US-ID>/functional.md.
- Cover:
- happy path Main Flow;
- every Business Rule;
- every Post-condition;
- negative cases for auth, payments, integrations, retries, and background jobs.
- Fill each TC's
Executable: path.
- Author executable spec scaffolding at the
Executable: path. Use one test per TC ID and keep the TC ID at the start of the runner test name.
- For non-UI tests, write full assertions.
- For UI tests:
- Use selectors from
docs/instrumentation-contract.md when available.
- If a needed selector is missing, write a literal
TODO: instrumentation-contract -- <purpose> marker in the framework's comment syntax and file a paired docs/open-issues.md entry with Category: selector-pending-contract.
- Emit
plan-update.json notes with selector TODO count.
Pass 2 Procedure
- Read
docs/instrumentation-contract.md.
- For every dispatched TC/spec carrying
TODO: instrumentation-contract, replace the marker with the declared selector.
- If a selector is still missing from the contract, keep the marker and raise/update an open issue against SA.
- Reverse-check coverage: every contract ID for the affected surface should appear in at least one spec. File
instrumentation-coverage-gap for unused IDs.
- Resolve paired
selector-pending-contract issues that were fully backfilled.
- Emit
plan-update.json notes with selectors backfilled and issues resolved.
Marker Syntax
Use the literal marker so QA-Exec can grep it:
| Runner | Marker |
|---|
| Playwright / Detox / Patrol / XCUITest / Espresso / AltTester | // TODO: instrumentation-contract -- <purpose> |
| Maestro YAML | # TODO: instrumentation-contract -- <purpose> |
Hard Rules
- Translate signed-off Acceptance Scenarios; do not invent new scenarios.
- Do not invent selectors.
- Pass 1 specs with TODO markers are intentionally unrunnable.
- Every executable TC must have a spec file.
- Commit before signaling ready-to-finalize.
