ATDD from an acceptance-criteria list - tags, stubs, traceability

Deep reference for gherkin-from-stories ("from an acceptance-criteria list" input shape). Consult when the team practices ATDD and needs the full tagged-scenario, red-first, traceability workflow.

Per ISTQB Glossary V4.7.1, ATDD (Acceptance Test-Driven Development) is "a collaboration-based test-first approach that defines acceptance tests in the stakeholders' domain language" (https://glossary.istqb.org/en_US/term/acceptance-test-driven-development). The flow: Story → AC → Acceptance test → Implementation → Pass. The acceptance test is written first; the implementation follows; success = test passes.

One tagged test per AC

Input AC list (each AC has an ID - preserved end-to-end so test failures map back):

## Acceptance criteria

- AC-1.1: Valid promo "WELCOME10" reduces subtotal by 10%.
- AC-1.2: Expired promo shows the message "This code has expired."
- AC-1.3: Empty promo input shows "Please enter a code."
- AC-1.4: Already-applied promo shows "Already applied" without re-applying.
- AC-1.5: Promo applies before tax (per current pricing logic).

# Features/promo-application.feature
Feature: Apply promo code at checkout

  Background:
    Given a logged-in customer
    And the cart contains 1 of "BOOK-001" at $24.99

  @AC-1.1
  Scenario: Valid promo reduces subtotal
    Given promo code "WELCOME10" is active
    When I enter "WELCOME10" in the promo input
    And I click "Apply"
    Then the subtotal updates to $22.49

  @AC-1.2
  Scenario: Expired promo shows error
    Given promo code "EXPIRED50" is inactive
    When I enter "EXPIRED50" in the promo input
    And I click "Apply"
    Then an error appears: "This code has expired"

  @AC-1.3
  Scenario: Empty promo input
    When I enter "" in the promo input
    And I click "Apply"
    Then an error appears: "Please enter a code"

  @AC-1.4
  Scenario: Already-applied promo
    Given promo code "WELCOME10" is active
    And I have already applied "WELCOME10"
    When I enter "WELCOME10" in the promo input
    And I click "Apply"
    Then an error appears: "Already applied"
    And the subtotal remains $22.49

  @AC-1.5
  Scenario: Promo applies before tax
    Given the tax rate for this region is 10%
    And promo code "WELCOME10" is active
    When I enter "WELCOME10" in the promo input
    And I click "Apply"
    Then the subtotal updates to $22.49
    And the tax updates to $2.249 (10% of $22.49)
    And the total is $24.74

The @AC-X.Y tag is the load-bearing traceability: failing tests report which AC failed.

Initial state - all tests fail

Per ATDD, tests are written before implementation. Initial run:

Scenario: Valid promo reduces subtotal
  Given promo code "WELCOME10" is active           # PASS (admin seeding works)
  When I enter "WELCOME10" in the promo input      # PASS (input field exists)
  And I click "Apply"                              # PASS (button exists)
  Then the subtotal updates to $22.49              # FAIL - promo logic not implemented

5 of 5 scenarios FAILED (as expected - implementation pending).

The failing tests are the work backlog. Implementation drives them green one by one; the story is "done" only when all AC tests pass - per the team's DoD (definition-of-done in the qa-process plugin).

Scaffold new step definitions

Detect undefined steps and emit stub definitions whose bodies raise:

# features/steps/promo_steps.py

@given('promo code "{code}" is active')
def step_promo_active(context, code):
    raise NotImplementedError(f"Implement: seed promo {code} as active")

@when('I enter "{code}" in the promo input')
def step_enter_promo(context, code):
    raise NotImplementedError(f"Implement: type {code} in promo input")

@then('an error appears: "{message}"')
def step_error_appears(context, message):
    raise NotImplementedError(f"Implement: assert error message {message}")

@then('the subtotal updates to ${expected:f}')
def step_subtotal(context, expected):
    raise NotImplementedError(f"Implement: assert subtotal == {expected}")

The NotImplementedError body makes the test failure helpful - the engineer knows exactly what to implement. Auto-generated step bodies that pass silently are the cardinal ATDD sin: tests appear green while production code never runs.

Traceability artifact

## AC-to-test mapping - `<story>` (auto-generated)

| AC ID  | Test                                             | Status  | Last run |
|--------|--------------------------------------------------|---------|----------|
| AC-1.1 | `promo-application.feature:8` (Valid promo)      | pass    | 2026-05-05 |
| AC-1.2 | `promo-application.feature:14` (Expired)         | pass    | 2026-05-05 |
| AC-1.3 | `promo-application.feature:20` (Empty)           | pass    | 2026-05-05 |
| AC-1.4 | `promo-application.feature:25` (Already applied) | pass    | 2026-05-05 |
| AC-1.5 | `promo-application.feature:32` (Tax interaction) | pass    | 2026-05-05 |

**Coverage:** 5/5 AC covered by tests. Story is testable per ATDD.

This artifact answers "Did we test what the customer asked for?" - a 1:1 mapping of AC → test → status answers it definitively, and closes the compliance / audit gap.

Run via the team's framework

Default: match the team's existing BDD runner - ATDD lives or dies by adoption, and forcing a runner switch alongside test-first authoring stalls both. Use the incumbent runner (Cucumber-JVM, Behave, or Reqnroll). Pick a new runner only when no incumbent exists; then default to the production stack's primary language (JVM → Cucumber-JVM, Python → Behave, .NET → Reqnroll).

# Cucumber-JVM
mvn test -Dcucumber.filter.tags='@AC-1.1 or @AC-1.2 or @AC-1.3 or @AC-1.4 or @AC-1.5'

# Behave
behave --tags=@AC-1.1 --tags=@AC-1.2 --tags=@AC-1.3 --tags=@AC-1.4 --tags=@AC-1.5

# Reqnroll
dotnet test --filter "Category=AC-1.1|Category=AC-1.2|..."

ATDD-specific anti-patterns

Manual test steps to declarative Gherkin - classification and rewrite rules

Deep reference for gherkin-from-stories ("from manual test steps" input shape). Consult when migrating manual scripts (TestRail / Qase / Xray exports) to BDD or handing a manual script to an automation engineer.

A manual test script and a Gherkin scenario describe the same behavior at different abstraction levels. Manual scripts are imperative ("click the Add to Cart button, then verify the cart count is 1"); Gherkin steps should be declarative ("the customer adds a product to their cart, then their cart shows one item"). The conversion goes wrong in a predictable way: one-for-one translation of UI mechanics produces brittle, implementation-coupled scenarios that Cucumber's own guidance warns against (https://cucumber.io/docs/bdd/better-gherkin/).

Step 1 - Classify each manual step

UI mechanics and state assertions are the two types to rewrite. Business actions are already declarative - pass them through. Setup converts to Given. Observations are typically dropped from Gherkin and lifted into step-definition implementation details.

Step 2 - Declarative-rewrite rules

The test for whether a step is too imperative: would the wording need to change if the implementation changed (e.g., the UI moved from a button to a voice command)? If yes, rewrite (https://cucumber.io/docs/bdd/better-gherkin/).

Rule R1 - Remove UI mechanics

Rule R2 - Collapse multi-step UI sequences into one business action

A manual script that says "type email; type password; click Submit" becomes one Gherkin step: When the customer signs in with valid credentials. The business action is "signing in", not "clicking, typing, clicking". The mechanics live in the step definition.

Rule R3 - Replace UI properties with observable outcomes

Rule R4 - Choose the right keyword

And and But inherit the type of the previous keyword - they are not interchangeable with Given/When/Then (https://cucumber.io/docs/gherkin/reference/).

Rule R5 - Preserve the project's existing vocabulary

Before emitting the rewrite, scan the project's existing Gherkin for the same business action. If "the customer signs in" is already used, do not introduce "the user logs in" - vocabulary drift fragments the step library and forces step-definition duplication. bdd-step-library-curator audits and consolidates that vocabulary.

Step 3 - Emit a side-by-side rewrite table

Output is a markdown table so a reviewer can confirm semantic equivalence:

The surviving rows assemble into a Scenario:

Scenario: Customer adds an in-stock product to their cart
  Given the customer is signed in
  When the customer adds SKU-001 to their cart
  Then their cart contains one item

Step 4 - Validate against project conventions

1. Check the project step library for matching existing steps; flag new steps for bdd-step-library-curator review.
2. Confirm the scenario has at most one When. Multiple Whens indicate two scenarios were collapsed; split them.
3. Lint with the project's Gherkin linter (gherkin-lint, picklesdoc, or the IDE's built-in).
4. Diff the rewrite against the manual step's expected outcome - semantic equivalence is the bar. If the manual step asserts "cart count is 1" but the rewrite asserts "cart is non-empty", that is a regression in specificity, not a successful abstraction.

Migration-specific anti-patterns

Migration-specific limitations

• Vocabulary alignment is the bottleneck, not translation. For large projects, run bdd-step-library-curator first to canonicalize vocabulary.
• Some manual steps are inherently UI-mechanical. A11y tests asserting "the Skip to main link is the first focusable element" cannot be rewritten into business language without losing the spec - pass through with R1 disabled and tag @a11y for the team to decide.
• Numerical specificity is preserved, not abstracted. "Cart count is 1" stays "cart contains one item" - not "cart is non-empty".
• Output is a draft. A human reviews the side-by-side before merging.

Sources

• Cucumber - Better Gherkin (declarative vs imperative): https://cucumber.io/docs/bdd/better-gherkin/
• Cucumber - Gherkin reference (keyword semantics): https://cucumber.io/docs/gherkin/reference/
• ISTQB glossary - test procedure (the imperative form abstracted away from): https://glossary.istqb.org/en_US/term/test-procedure

Extracting acceptance criteria from raw specs - worked examples

Deep reference for gherkin-from-stories ("from a raw spec / PRD" input shape). Three end-to-end examples of natural-language spec text turned into acceptance criteria; the extraction method lives in the SKILL.md section.

Example 1: simple story -> 2 scenarios

Input (Linear story):

"Title: Email update on profile page

As a logged-in user, I want to update my email address from /profile/settings. After update, the email field shows the new value and I see a confirmation toast."

Output:

Feature: Email update on profile page

  As a logged-in user
  I want to update my email address from /profile/settings
  So that my account contact information stays current

  Background:
    Given a logged-in user with email confirmed
    And the user is on the /profile/settings page

  Scenario: Update email to a new valid address
    When the user changes the email field to "new@example.com"
    And the user clicks "Save profile"
    Then the email field shows "new@example.com"
    And a [data-testid="profile-saved-toast"] is visible

  Scenario Outline: Email update validation rejects invalid input
    When the user changes the email field to "<invalid_email>"
    And the user clicks "Save profile"
    Then the email field shows the previous value
    And a [data-testid="email-validation-error"] is visible

    Examples:
      | invalid_email           |
      | not-an-email            |
      | missing@                |
      | @example.com            |
      | spaces in@email.com     |

Example 2: PRD with implicit preconditions

Input (PRD excerpt):

"We will allow promo codes at checkout. Codes apply 20% off the subtotal."

Output:

## Implicit-precondition flags (3)

1. **Code source.** Where do codes come from - user-entered? auto-applied? Both?
2. **Eligibility.** Are codes user-tier specific (e.g. only new users)?
   Time-limited? Per-user limited?
3. **Subtotal definition.** Subtotal *before* tax / shipping, or *after*?

Without these answers, the test suite cannot be written.

Never fabricate the missing pieces - return a question list to the PRD author instead.

Example 3: Scenario Outline opportunity

Input:

"Login should work for active accounts (returning 200) but reject suspended (401), unverified (403), and non-existent (404) accounts."

Output:

Feature: Login authorization

  Scenario Outline: Login response per account status
    Given an account with status "<status>"
    When the user submits valid credentials
    Then the response status is <http_status>
    And the response body contains "<error_code>"

    Examples:
      | status        | http_status | error_code           |
      | active        | 200         |                       |
      | suspended     | 401         | ACCOUNT_SUSPENDED    |
      | not_verified  | 403         | EMAIL_NOT_VERIFIED   |
      | not_found     | 404         | ACCOUNT_NOT_FOUND    |