ln-42-acceptance-test-builder

# Acceptance Test Builder

**Goal:** Deliver the smallest trustworthy acceptance-test portfolio for stated requirements through a user- or external-system-observable boundary. Modify only approved tests and test documentation; implement justified additions, updates, merges, and deletions without repairing product code.

**Execution contract:** Treat the ordered checkbox workflow below as this skill's Definition of Done. Track every checkbox as `PENDING`, then resolve it to `PROVEN` with concrete evidence, `CLEARED` with evidence that its conditional trigger is absent, or `UNPROVEN`; reading, mentioning, delegating, skipping, or tool failure is not proof.
Before returning, resolve every `PENDING`, count only `PROVEN` and `CLEARED` items as complete, apply this skill's verdict, decision, and approval rules to every `UNPROVEN`, and prepend **Checklist: X/Y complete**<br>**Incomplete: None | section/item — reason; outcome impact; exact next action**; list every `UNPROVEN` item.

## Tool Routing

| Need | Preferred tool | Use it when | Fallback |
|---|---|---|---|
| Workspace safety | Git status, diff, repository instructions, and branch or worktree inspection | Always before editing | Stop when user changes cannot be separated safely |
| Existing test conventions | File listing, search, manifests, runner configuration, CI, and focused reads | Selecting the project-native runner, layout, fixtures, and commands | Follow the nearest maintained test pattern |
| Behavior and wiring | Language server or host-native code intelligence | Locating observable entrypoints, registration, consumers, and state boundaries | Narrow search plus direct inspection |
| Test implementation | Native editing tools and project generators | Creating tests, fixtures, helpers, and narrowly required test documentation | Minimal project-consistent files; never hand-edit generated state |
| Observable execution | Repository-defined shell commands, browser, API client, CLI, or disposable integration environment | Proving UI, protocol, command, or durable state outcomes | Return `INCOMPLETE` with the exact missing check |
| External contract | Official version-matched documentation or specification | Expected behavior depends on a current external API or standard | Mark it `UNVERIFIED`; do not encode a guessed oracle |

Never run acceptance tests against production or an unapproved external target. Do not deploy, publish, migrate shared data, rotate credentials, or accept changed output merely to make a test pass.

## Evidence Rules

- Derive expected behavior from requirements, public contracts, examples, invariants, or an independent reference; never from the implementation calculation being tested.
- Prefer a terminal durable or user-visible outcome over an intermediate status, mock call, log line, or internal method result.
- Use golden files or snapshots only for deterministic, reviewable contracts. Updating expected output is a specification change, not test verification.
- Make setup, data allocation, execution, cleanup, and rerun behavior reproducible; preserve the first failure before retries or cleanup obscure it.
- A passing command proves only the environment and scenarios it actually exercised. State every excluded cell and unavailable boundary.
- Do not test language, framework, package, database-vendor, or other generic behavior; test only the repository-owned observable contract, configuration, integration, or policy that depends on it.
- Treat `KEEP`, `ADD`, `UPDATE`, `MERGE`, `DELETE`, and `NO_TEST` as portfolio decisions, distinct from execution results. Do not default to `ADD` when existing evidence, consolidation, retirement, or accepted residual risk is the better answer.
- Delete or merge only when the test basis is obsolete or evidence shows that all still-required unique material behavior, failure modes, oracle strength, and useful failure localization remain covered.

## Checklist

### 1. Establish the Change Boundary

- [ ] Resolve the requirements, acceptance criteria, actor, protected outcome, observable contract, explicit non-goals, approved portfolio decisions, allowed test paths, and allowed test-documentation paths; label inferred experience qualities as assumptions.
- [ ] Read applicable repository instructions and inspect Git state, untracked files, generated areas, and existing user changes before editing.
- [ ] Detect the project-native runner, directory layout, naming, fixtures, setup, cleanup, environment configuration, and CI invocation.
- [ ] Inventory existing tests affected by the requirement or contract and map their actual oracles before creating a new test.
- [ ] Map each requirement to the boundary that can prove it: UI, API, CLI, message, integration, file, or durable state.
- [ ] Identify credentials, services, accounts, ports, devices, browsers, datasets, and destructive effects required by the scenarios.
- [ ] Return `BLOCKED` before editing when no safe target, reliable expected contract, or separable workspace exists.

### 2. Design Reproducible Acceptance Evidence

- [ ] Define the protected outcome, defect class, setup, action, terminal outcome, independent oracle, expected evidence, and cleanup for every requirement.
- [ ] Confirm or derive one portfolio action per affected test and material risk. When no approved strategy exists, justify the action from impact, plausible failure, uniqueness, trust, and maintenance cost; record `NO_TEST` with existing proof, another control, or accepted residual risk.
- [ ] Prefer deterministic end-to-end evidence for material user-observable business risk. Use a narrower production-shaped contract or integration boundary only when it still proves the terminal outcome more deterministically or precisely; never replace acceptance evidence with a unit implementation check or cover an internal detail absent from the observable contract.
- [ ] Include invalid, authorization, boundary, partial-failure, retry, idempotency, recovery, and com