| name | add-acceptance-test |
| description | Add acceptance tests under a functional spec in a ***plain spec file. Use when the user wants to add verification criteria for a specific functional spec, or after adding a functional spec that needs testable success criteria. |
Add Acceptance Test
Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.
Workflow
- Identify the target
.plain file and the functional spec to attach the acceptance test to. If ambiguous, ask the user.
- Read the file to understand the functional spec, existing acceptance tests (if any), and the
***test reqs*** section (acceptance tests are implemented according to test reqs).
- Draft the acceptance test(s) following the rules below.
- Nest them under the target functional spec using a
***acceptance tests*** subsection.
- Read the file again to confirm correct placement, indentation, and syntax.
When to Add Acceptance Tests
- The functional spec's correct behavior is non-obvious or easily misinterpreted.
- The spec involves edge cases, boundary conditions, or specific numeric outcomes.
- The user explicitly requests verification criteria.
- The spec was added via the
add-functional-spec skill and warrants testable success criteria.
Format
Acceptance tests are nested under the functional spec they verify, using a ***acceptance tests*** subsection:
***functional specs***
- The system should process :Task: items in batches of 100.
***acceptance tests***
- Processing 250 :Task: items should result in 3 batches.
- Each batch should contain at most 100 items.
Key formatting rules:
- The
***acceptance tests*** header is indented under the functional spec it belongs to.
- Each test bullet is indented under the
***acceptance tests*** header.
- Multiple acceptance tests can be listed under a single functional spec.
Line syntax (hard rule)
Every line inside ***acceptance tests*** must be its own list item starting with - . ***plain has no concept of bare continuation lines — indented prose without a leading - is invalid syntax and the renderer will reject it.
- Hard limit: 120 characters per line. If a sentence is too long, split it at a natural clause boundary into nested
- bullets — never wrap onto an unprefixed line.
- Nested clarifications are also
- items, indented under the parent. The indentation alone is not enough; the leading - is required.
BAD — bare continuation lines (invalid ***plain syntax, will not render):
***acceptance tests***
- Processing 250 :Task: items should result in 3 batches with the
last batch containing the remaining 50 items.
GOOD — every line starts with - :
***acceptance tests***
- Processing 250 :Task: items should result in 3 batches.
- The first two batches each contain 100 items.
- The last batch contains the remaining 50 items.
Rules
Conformance with the Functional Spec
An acceptance test is essentially an example that illustrates the functional spec — it clarifies intent by showing a concrete scenario. It may imply minor code changes, but those should not be substantial. The acceptance test must be consistent with the functional spec it is nested under. If the acceptance test asserts behavior that contradicts, narrows, or extends the functional spec in ways not implied by it, the system will reject it as a conflicting acceptance test. Before writing, re-read the parent functional spec and ensure every assertion in the acceptance test is a direct, logical consequence of what the spec states.
Functional spec:
- The system should return :Resource: items sorted by creation date in descending order.
Good (consistent):
- The first :Resource: in the response should have the most recent creation date.
Bad (contradicts the spec — the spec says descending, not ascending):
- The first :Resource: in the response should have the oldest creation date.
Bad (extends beyond the spec — the spec says nothing about limiting results):
- The response should contain at most 50 :Resource: items.
Scope
Each acceptance test verifies a specific, observable aspect of the functional spec it's nested under. Do not test behavior from other functional specs.
Testability
Every acceptance test must describe a concrete, verifiable outcome — not a vague quality. The test should be implementable as an automated conformance test.
Good: - The response should contain exactly 3 items.
Bad: - The response should be correct.
Language Agnosticism
Like functional specs, acceptance tests must be written in terms of behavior and outcomes — not language-specific constructs.
Relationship to Test Reqs
Acceptance tests extend conformance tests and are implemented according to the ***test reqs*** specification. They do not replace test reqs — they add spec-specific verification on top of the general testing framework defined there.
Validation Checklist
