Immutable. This exact content is served forever at /api/v1/blob/767d17d4a054a640.
--- name: ln-42-acceptance-test-builder description: "Creates, updates, consolidates, retires, and runs scoped acceptance tests using project-native tooling. Use when executable acceptance evidence must change; not for audits or product fixes." --- # 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 compatibility behavior only when it can materially change the protected outcome. - [ ] Allocate unique or namespaced test data and control clock, randomness, locale, ordering, and concurrency where they affect reproducibility. - [ ] Use real dependencies or approved emulators when mocks would bypass the behavior under acceptance; pin versions and verify readiness and reset behavior. - [ ] For deterministic output, derive golden or diff expectations from an independent contract and keep the artifact small enough to review. - [ ] For nondeterministic output, assert stable invariants and semantic fields instead of normalizing away failures or snapshotting noise. - [ ] Locate UI and other interaction elements only through stable repository-owned IDs or dedicated test hooks; never locate by visible or translated copy, styling, layout, position, or incidental structure, and assert exact copy separately only when it is an explicit contract. - [ ] Define the required or diagnostic gate and a review or retirement trigger when evidence is temporary, compatibility-bound, incident-specific, or coupled to a changing contract. ### 3. Implement within Test Scope - [ ] Create or update tests in the existing project layout with behavioral names and failure messages that identify the violated requirement, protected outcome, and detected defect. - [ ] Implement approved `MERGE` and `DELETE` actions without leaving superseded tests, fixtures, snapshots, helpers, registrations, or CI entries; preserve replacement traceability in repository-native paths, names, tags, or task evidence. - [ ] Reuse maintained fixtures and helpers only when their defaults and side effects remain visible; avoid a new abstraction for one scenario. - [ ] Make setup fail fast on missing prerequisites and make cleanup safe after success, assertion failure, timeout, cancellation, or partial setup. - [ ] Keep tests rerunnable and idempotent; do not depend on execution order or silently reuse state from a previous run. - [ ] Add the narrowest required test documentation only when contributors otherwise cannot configure, run, interpret, or clean up the new evidence. - [ ] Do not edit production code, weaken assertions, broaden timeouts without evidence, skip failing cases, or regenerate expected artifacts to obtain a pass. - [ ] Inspect the diff for unrelated formatting, generated churn, secrets, environment-specific paths, and changes outside the approved scope. ### 4. Execute and Preserve Evidence - [ ] Run the smallest affected scenario first, then the relevant suite and required repository gate when available; when actions only remove evidence, run the replacement or nearest retained proof. - [ ] Record the exact command, working directory, environment class, target, versions, exit status, duration, and artifact locations. - [ ] Preserve the first failing output, seed, order, request, response, screenshot, diff, or durable state needed to reproduce the defect. - [ ] Distinguish product failure, test defect, environment failure, unavailable dependency, and flaky evidence before changing the test. - [ ] If the test exposes a product defect, stop modifying the implementation, retain the failing acceptance evidence, and report the smallest reproduction. - [ ] Verify cleanup and rerun at least the affected scenario when state ownership or idempotency is material. - [ ] Avoid retries unless they diagnose nondeterminism; a retry must not convert the initial failure into a silent pass. ### 5. Finalize without Overclaiming - [ ] Map every requirement and protected outcome to its final test path or `NONE`, command or alternative control, oracle or accepted risk, and result as `PASS`, `FAIL`, `BLOCKED`, or `UNPROVEN`. - [ ] Reconcile planned and actual portfolio actions, including justified deviations, and report the net count of tests added, updated, merged, and deleted without treating counts as quality targets. - [ ] Use `COMPLETE` when all approved portfolio actions are implemented and required acceptance evidence executes to a recorded `PASS` or `FAIL`; this verdict describes evidence completion, not product correctness. - [ ] Use `INCOMPLETE` when actions are implemented but an environment, dependency, or interrupted run prevents complete execution; state the exact missing check. - [ ] Use `BLOCKED` when actions cannot be implemented safely, requirements lack a reliable oracle, or the workspace cannot be protected. - [ ] Return created, changed, merged, and deleted test files, commands, evidence, cleanup result, limitations, product defects, and residual risks. ## Output Contract ```markdown # Acceptance Test Build **Verdict:** COMPLETE | INCOMPLETE | BLOCKED ## Scope and environment - Requirements and approved paths - Runner, boundary, target, and prerequisites ## Requirements matrix | Protected outcome and test basis | Existing evidence or affected test | Action | Final test | Oracle and command | Gate and result | Review or retirement trigger | |---|---|---|---|---|---|---| | ... | path / command / NONE | KEEP / ADD / UPDATE / MERGE / DELETE / NO_TEST | path / NONE | ... | required / diagnostic; PASS / FAIL / BLOCKED / UNPROVEN | ... | ## Changes and evidence - Created or changed test and documentation files - Deleted or consolidated tests and their replacement evidence; net portfolio effect - Exact commands, outputs, and evidence artifacts - Product defects preserved without repair ## Cleanup, limitations, and residual risks State cleanup, unavailable environments, excluded cells, and remaining evidence needs. ```