| name | atdd |
| description | Pragmatic Acceptance Test-Driven Development — agree concrete examples with stakeholders (Discuss), capture them as executable acceptance checks (Distill), then implement with outside-in delivery (Develop). Supports Gherkin/Cucumber when it helps, code-first acceptance tests, and contract tests at service boundaries. Composes with the inner-loop TDD skill for programmer tests. Use when defining story done, writing acceptance or executable specifications, or aligning business examples with automation before feature code. |
| allowed-tools | Read, Edit, MultiEdit, Bash, Grep, Glob |
Pragmatic ATDD (outside-in)
Mission
Turn business intent into concrete, automated examples before (or as) the team builds the feature — so programmers and stakeholders mean the same thing when they say “done.”
First step of every capability slice: agree examples (scenarios, tables, or outcomes) and record them in a tracked artifact in the repo (path rules in references/example-catalog.md).
Distill step: turn the highest-value examples into at least one failing automated acceptance check at the right layer (see references/environments-and-test-pyramid.md) — unless the slice is explicitly example-only (UI mock) with a written deferral. For feasibility unknowns, use skills/spike on a spike/ branch first, then return here after promotion.
Develop step: make acceptance green using outside-in work; use strict TDD (skills/tdd) for inner-loop programmer tests.
Optimize for:
- shared understanding (examples beat abstract requirements)
- executable definition of done (automated where practical)
- right layer (contract or narrow acceptance over slow full-stack when that still proves the business outcome)
- living documentation readable by non-programmers when possible
- composition with inner TDD — not duplication at every layer
This skill covers the outer acceptance loop. It does not replace unit TDD, bugfix workflows, CI pipeline design, or product discovery — compose with other skills for those.
Discuss → Distill → Develop (pragmatic)
1. Discuss — agree examples
Who: business representative, developer, and someone who thinks about quality (the “triad” / three amigos) — roles can be played by the same person on small teams.
Test strategy: Before Distill, evaluate layers and specialized techniques per test-strategy-selection.md and checklists/pipeline-fit.md — contract vs API vs E2E; property-based or mutation only when they add evidence unit/acceptance cannot.
Output: concrete examples with agreed data, terminology, and boundaries — not a long specification document.
Practices:
- Start from a user story or capability and ask: “How would we manually check this is right?”
- Capture happy path, important edges, and failure the business cares about now.
- Use tables or Given / When / Then language when it helps clarity; plain bullet examples are fine.
- Record outcomes in the example catalog file before coding (see reference).
See references/collaboration-and-examples.md.
2. Distill — automate the agreement
Transform agreed examples into executable checks:
| Approach | When (pragmatic) |
|---|
| Gherkin + runner (Cucumber, SpecFlow, pytest-bdd, etc.) | Stakeholders will read scenarios in PRs; team already uses BDD tooling |
| Code-first acceptance (Playwright, API tests, RSpec feature specs) | Faster for the team; examples stay in catalog + test names/assertions |
| Contract tests (Pact, schema/contract suites, consumer-driven contracts) | Service boundary is the capability; business outcome is “honors agreed contract” |
| Narrow acceptance (HTTP against app, in-process acceptance module) | Full E2E is slow/flaky but business rule can be proven at a stable seam |
Rules:
- Prefer one failing acceptance check that proves the next agreed example — not a suite of ten scenarios upfront.
- The check must fail for the right reason (missing behavior), not environment noise — see references/quality-and-flake-control.md.
- Do not block Distill on perfect Gherkin if code-first is the repo norm — keep the catalog as the human-readable source of truth.
See references/discuss-distill-develop.md and references/gherkin-and-bdd-tooling.md.
3. Develop — outside-in, then inner TDD
- Acceptance RED: failing automated check for the current example.
- Inner loop: use
skills/tdd — test list + R–G–R — to grow production code until acceptance can pass.
- Acceptance GREEN: run the acceptance check; widen scope only when touching shared setup.
- Repeat for the next open example in the catalog.
Refactor when acceptance and programmer tests are green; keep acceptance assertions at outcomes, not incidental UI structure.
See references/executable-specifications.md and references/acceptance-vs-programmer-tests.md.
Example catalog (mandatory)
The catalog is a Markdown file in the repo listing business-visible examples for the slice — the outer-loop counterpart to TDD’s test list.
Before Distill (automation) for a slice:
- Choose folder: project convention, else
acceptance-examples/ at repo root (see references/example-catalog.md).
- Create
<stem>.md from branch and/or feature name (kebab-case).
- List each example as
[ ] with Given / When / Then or a short scenario + key data.
- During work: flip to
[x] when an automated acceptance check exists, passes, and is referenced on the line.
- Slice done when agreed examples are
[x] (or documented as deferred/removed) and relevant suites are green.
Refactor-only or internal tech tasks do not belong in the catalog — use a sibling -follow-ups.md or the closing reply (same pattern as TDD test list).
Relationship to TDD (inner loop)
| Concern | ATDD (this skill) | TDD (skills/tdd) |
|---|
| Question | “Did we build the right thing for the business?” | “Is each unit well built?” |
| Granularity | Story / capability / boundary | Class / module / function |
| Artifact | Example catalog + acceptance checks | Test list + unit tests |
| Audience | Business-readable examples | Programmers |
Compose: one acceptance example → inner TDD until green → next example. Do not re-assert every business rule in unit tests if acceptance already proves it at a stable seam — unit tests should cover design pressure, edges the acceptance layer is too coarse to catch, and fast feedback on logic.
When not to use ATDD (use TDD only)
For skills/new-increment and similar inner work:
- Domain logic, katas, libraries, single-package modules with no separate deployable boundary
- When acceptance tests would call the same in-process API with the same assertions as unit tests
Use skills/tdd and test-lists/<feature>.md only. See skills/new-increment/references/scoped-atdd-tdd.md and artifact-policy.md.
Language-agnostic execution
Adapt to the repository:
- detect existing acceptance, BDD, E2E, or contract tooling
- follow project layout for features, specs, and tags
- run the smallest acceptance command that covers the current example
Never assume Cucumber, Playwright, or a specific folder; inspect first.
Tooling orientation: references/gherkin-and-bdd-tooling.md.
Pragmatic commit flow
Match team conventions when they exist. Default story for a single acceptance example:
| Step | Typical content | Suggested prefix |
|---|
| Distill (RED) | acceptance spec / scenario / contract only | test: |
| Develop (GREEN) | production + any glue to pass acceptance | feat: |
| Refactor | structure, step defs, helpers — behavior unchanged | refactor: |
Squash per team policy (many teams squash per story; TDD skill squashes per unit cycle — do not mix the two rhythms in one commit message without intent).
Inner unit cycles still follow skills/tdd micro-commits when that skill is active.
Anti-patterns (summary)
- Coding before any agreed example (surprise delivery).
- UI click scripts masquerading as business scenarios (see Gherkin reference).
- One giant E2E as the only acceptance test for a large story.
- Duplicating every acceptance assertion in dozens of unit tests.
- Flaky acceptance that the team ignores (definition of done erodes).
- Catalog lines marked
[x] without a test reference or passing automation.
- Using acceptance tests for all regression (wrong layer — use unit/integration too).
Full list: references/anti-patterns.md.
Definition of done
One acceptance example
- Example agreed in Discuss and recorded in the catalog.
- Distill: failing automated check at chosen layer; failure is intentional.
- Develop: acceptance green; inner TDD test list items for this example are
[x] or explicitly deferred.
- Catalog line
[x] with automation reference (path, scenario name, or contract id).
Capability slice
- Example catalog file exists and was maintained through the slice.
- All in-scope examples
[x] or documented under Deferred / Removed.
- Acceptance suite (and unit suite, if composed) green.
- All applicable project verify steps for this scope passed (
docs/delivery-process.md §2; docs/project-verification.md) — lint, format, typecheck, SonarQube/static analysis when configured.
- Test strategy table delivered (
docs/test-strategy-selection.md §6).
- No undeclared business behavior shipped.
Checklists: checklists/story-readiness.md, checklists/scenario-and-test-quality.md, checklists/pipeline-fit.md.
Output format
## Capability: <name>
### Example catalog
- Path: `<e.g. acceptance-examples/order-shipping-threshold.md>`
- Branch / slug: <optional>
### Examples (excerpt; source of truth is the file)
- `[x]` lines must show automation back-reference
### Discuss → Distill → Develop (latest example)
#### Discuss
- Agreed example: <one line>
- Data / terms: <bullets>
#### Distill (acceptance RED)
- Check: <file::scenario or test name>
- Layer: <e2e | api | contract | in-process>
- Failure: <short message>
#### Develop
- Inner TDD: <test list path, cycles summary or "composed with tdd skill">
- Acceptance: <command scope> — green
### Commits (if applicable)
- test: … / feat: … / refactor: …
### Slice status
- Catalog: `<path>` — all `[x]` | N open
- Follow-ups: `<path or "in closing reply">`
Additional resources
References
Examples
Checklists
Resource usage
Open reference files when layer choice, catalog format, Gherkin quality, or acceptance vs unit boundaries are unclear.
