Generate BDD Scenarios — and Detect the Vague Steps Before They Calcify

Tier: Foundation · Workflow area: Test design & planning

This playbook generates Given/When/Then scenarios from acceptance criteria with step-definition scaffolding for Cucumber or Behave, then runs a dedicated vague-step detection pass. Vague steps are the BDD-specific hallucination: syntactically perfect, semantically empty, and expensive to unwind once automated.

When to use

• Teams already practicing BDDGherkin is your shared language and scenarios feed automation via Cucumber, Behave, or SpecFlow successors.
• ACs exist but scenarios don'tthe classic backlog debt where stories shipped with prose criteria and no executable specs.
• Three-amigos preparrive with a candidate scenario set to argue about instead of a blank page.

When NOT to use:

• Teams not doing BDD. Generating Gherkin nobody automates or reads creates a second, staler copy of the requirements.
• Purely visual or exploratory concernslayout, feel, and usability don't decompose into Given/When/Then; charter those instead (pb-07) and keep Gherkin for behavior with observable outcomes.

Prerequisites

• A working BDD toolchainCucumber (cucumber-js), Behave, or equivalent, already running in the repo so dry-runs are possible from minute one.
• Numbered acceptance criteria for the stories in scope — tags will reference these numbers.
• Your existing step-definition catalog exported or listed — the single best defense against step-library drift is pasting it into the prompt.
• An approved assistant under your data policy for story content.

The recipe

1. 1.

   Generate scenarios with strict concreteness rules. The rules in the prompt are the difference between usable Gherkin and generic filler:

   Copy

   Convert these acceptance criteria into Gherkin scenarios for Cucumber.
   
   Hard rules:
   - Every Given/When/Then must reference CONCRETE values ("a cart totaling
     €149.99"), never abstractions ("some items").
   - No step may contain "correctly", "properly", "appropriately",
     "successfully", "as expected", or "valid/invalid" without defining it.
   - Use Scenario Outline + Examples tables when 3+ scenarios differ only
     in data.
   - Tag each scenario with its AC number: @AC-3.
   - If an AC is too vague to make concrete, output it under "CANNOT
     SPECIFY" with the question that needs answering. Do not guess.
   
   Acceptance criteria: [paste, numbered]
   

2. 2.

   Run the vague-step detector as a second pass. Fresh instruction, applied to the output — the model finds its own weasel words more reliably when critique is a separate task:

   Copy

   Audit these scenarios as a BDD coach. Flag every step that is:
   VAGUE (no observable pass/fail), UNBOUND (value left abstract),
   COMPOUND (two behaviors in one step), UI-COUPLED (asserts widget
   internals instead of behavior), or MISSING-ELSE (a When with no
   negative-path sibling scenario).
   Output: step text, flag, and a rewritten concrete version.
   

   Good output looks like this:

   Copy

   # FLAGGED — VAGUE:
   #   Then an appropriate error message is displayed
   # REWRITE:
   Then the message "Card declined — no funds were taken" is displayed
   And the order status remains "Draft"
   

3. 3.

   Apply your own pass over the flags. Accept, reject, or sharpen each rewrite. Watch for the detector's blind spot: steps that are concrete but assert the wrong thing entirely — only your product knowledge catches those.

4. 4.

   Scaffold step definitions and dry-run. Have the assistant generate matching step-definition stubs, then let the framework verify every step binds:

   Copy

   npx cucumber-js --dry-run features/checkout.feature
   

   Copy

   behave --dry-run features/checkout.feature
   

   Dry-run failures reveal the drift the model introduces between scenario wording and step patterns — fix wording toward your existing step vocabulary, not the other way around, or you fork the step library.

5. 5.

   Reuse before you add. Diff the generated steps against your existing step-definition library; every near-duplicate ("I log in" vs "I am logged in") the model invented should collapse into the established step. Paste your step catalog into the generation prompt next time to prevent the drift at the source.

Make it yours

• Behave/pytest-bdd (Python) shopssame recipe; scaffold @given/@when/@then functions and run behave --dry-run --no-snippets in CI so unbound steps fail the build permanently, not just at authoring time.
• Example Mapping first, generation secondfeed the mapped examples (rules, examples, questions) instead of raw ACs; the model turns each mapped example into a scenario nearly 1:1, and the CANNOT SPECIFY list is usually already empty.
• Living-documentation pipelinesif Gherkin publishes to stakeholders via Cucumber Reports or Pickles, add a tone rule to the prompt ("business-readable, no CSS selectors, no HTTP verbs in steps") and keep technical detail in the step definitions.

Quality check

• Zero banned-word steps survivegrep the feature files for "correctly", "properly", "appropriately", "as expected"; the count must be zero.
• Every Then is observablea new team member could decide pass/fail from the step text alone, without asking anyone.
• Dry-run is cleanno undefined or ambiguous steps in cucumber-js --dry-run/behave --dry-run output.
• Negative siblings existevery meaningful When has at least one scenario covering its failure path; count them per feature.
• Step library stayed coherentno new step that duplicates an existing one with different phrasing; diff reviewed by whoever owns the library.
• CANNOT SPECIFY items went to the product ownerthey are requirement defects found early, which is the entire economic point.