gherkin-from-stories · diff
git:20260724.d4db756 to git:20260813.83125c6
166 added, 101 removed. Audit A to A.
---
name: gherkin-from-stories
- description: "Build-an-X workflow that converts user stories into Gherkin scenarios - extracts the actor / capability / value triple from \"As a … I want … so that …\", maps acceptance criteria to Scenario blocks, identifies parameterizable axes for Scenario Outlines, and emits a Feature file ready for `bdd-step-library-curator`-curated step definitions. Starts from the story itself rather than from an already-extracted acceptance-criteria list; this skill operates at the user-story layer and produces Gherkin directly. Emits Gherkin only: no step definition stubs and no runner detection. For a full runnable artifact (Feature file plus scaffolded step definitions), follow this skill with step-definition scaffolding for the detected runner. Use when a PM hands over a user story or a backlog of stories and the team's first test artifact is the `.feature` file rather than a separate AC doc."
+ description: "Converts requirements in any input shape into Gherkin scenarios - a user story (\"As a … I want … so that …\"), a signed-off acceptance-criteria list (ATDD: @AC-N-tagged scenarios, NotImplementedError step stubs, AC-to-test traceability table), existing manual test steps (declarative rewrite that strips UI mechanics), or a raw spec / PRD section (acceptance-criteria extraction with Gherkin or plain-list output). Maps criteria to Scenario blocks, detects Scenario Outline opportunities, factors shared Background, reuses the curated step library, and flags implicit preconditions instead of fabricating them. Emits Gherkin (plus stubs in ATDD mode): runner detection and full step wiring belong to bdd-scenario-author. Use whenever requirements text of any shape needs to become a .feature file."
---
# gherkin-from-stories
## Overview
The shift-left flow:
```
- User story → Acceptance Criteria → Gherkin Feature → Step definitions → Tests
+ Spec / User story → Acceptance Criteria → Gherkin Feature → Step definitions → Tests
```
- `acceptance-criteria-extractor` (in the qa-shift-left plugin)
- covers the AC layer (it can emit Gherkin too). This skill is a
- **direct user-story → Gherkin** path for teams that author
- Gherkin features as the primary artifact (skipping the
- intermediate AC step).
+ This skill is the authoring umbrella for the left half of that flow: it
+ turns requirements text into a `.feature` file. Four input shapes route to
+ the same core transform:
+ | Input you have | Section to use | Extra output |
+ |---|---|---|
+ | A user story with the As-a / I-want / So-that triple | "From a user story" | - |
+ | A signed-off, numbered acceptance-criteria list | "From an acceptance-criteria list (ATDD)" | `@AC-N` tags, step stubs, traceability table |
+ | Already-written manual test steps (TestRail / Qase / Xray export, prose script) | "From manual test steps" | side-by-side rewrite table |
+ | A raw spec / PRD section with no AC structure yet | "Extracting acceptance criteria from a raw spec" | Gherkin or plain numbered AC list |
+
+ Whatever the input, the same core discipline applies: one Scenario per
+ behavior, Scenario Outline when only data varies, shared Background, step
+ library reuse, and flag-and-ask on implicit preconditions.
+
## When to use
- - The team's BDD process starts with user stories, not separate
- AC docs.
- - A PM hands engineers a story and the team's first artifact is
- the `.feature` file.
- - A migration from non-BDD to BDD wants to convert existing
- stories into Gherkin in bulk.
+ - A PM hands over a story, spec, or AC list and the team's first test
+ artifact is the `.feature` file.
+ - The team practices ATDD and gates stories on green acceptance tests.
+ - A team is migrating manual test scripts (or a whole TestRail / Qase
+ library) to BDD.
+ - A migration from non-BDD to BDD wants to convert existing requirements
+ into Gherkin in bulk.
- If the team uses AC docs as primary, use
- `acceptance-criteria-extractor` (in the qa-shift-left plugin);
- this skill is the user-story-first variant.
+ Not this skill: reviewing existing Gherkin for style (use
+ `gherkin-style-reviewer`); wiring step definitions to a runner end to end
+ (use `bdd-scenario-author`, which invokes this skill first); non-functional
+ requirements - perf / a11y / security thresholds have a different shape
+ (thresholds, not Given/When/Then) - use
+ `non-functional-requirement-extractor` in the qa-shift-left plugin.
- ## Step 1 - Extract the user-story triple
+ ## From a user story
+ ### Step 1 - Extract the user-story triple
+
```markdown
# Story: Apply promo code at checkout
**As a** logged-in customer
**I want** to apply a promotional code at checkout
**So that** I receive the advertised discount on my order
```
The triple maps to the Feature header:
```gherkin
Feature: Apply promo code at checkout
As a logged-in customer
I want to apply a promotional code at checkout
So that I receive the advertised discount on my order
```
- If the story doesn't have the triple, **flag and ask** - a story
- without explicit value is a signal the team should clarify before
- testing.
-
- ## Step 2 - Extract acceptance criteria
-
- The story body usually has a list:
-
- ```markdown
- ## Acceptance criteria
+ If the story doesn't have the triple, **flag and ask** - a story without
+ explicit value is a signal the team should clarify before testing.
- - Valid promo applies the discount and shows confirmation.
- - Expired promo shows an error message.
- - Invalid promo shows "Code not found."
- - Empty input shows "Please enter a code."
- - Already-applied promo shows "Already applied."
- ```
+ ### Step 2 - Map acceptance criteria to Scenarios
- Each AC becomes a Scenario:
+ The story body usually has an AC list; each AC becomes a Scenario:
```gherkin
Background:
Given I am a logged-in customer
And my cart contains 1 item at $24.99
Scenario: Apply valid promo
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
And a confirmation toast appears: "Code applied"
Scenario: Apply expired promo
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"
```
- ## Step 3 - Identify Scenario Outline opportunities
+ ### Step 3 - Identify Scenario Outline opportunities
- Multiple ACs that vary only in input data become a Scenario
- Outline:
+ Multiple ACs that vary only in input data become a Scenario Outline - use
+ one whenever the underlying logic is identical and only the data varies:
```gherkin
Scenario Outline: Promo validation rejects bad input
When I enter "<code>" in the promo input
And I click "Apply"
Then an error appears: "<error>"
Examples:
| code | error |
| EXPIRED50 | This code has expired |
| NOTREAL | Code not found |
| (empty) | Please enter a code |
| WELCOME10*2 | Already applied |
```
- Per `acceptance-criteria-extractor` (in the qa-shift-left plugin)
- Step 2: "Use Scenario Outline whenever the underlying logic is
- identical and only the data varies."
+ ## From an acceptance-criteria list (ATDD)
- ## Step 4 - Use existing steps from the library
+ When the input is a signed-off, numbered AC list and the team gates
+ implementation on green acceptance tests (per ISTQB, ATDD is "a
+ collaboration-based test-first approach that defines acceptance tests in
+ the stakeholders' domain language"):
- Per
- `bdd-step-library-curator`,
- the team has a curated step library. Use existing steps where
- possible:
+ 1. **One Scenario per AC**, tagged `@AC-X.Y` - the tag is the load-bearing
+ traceability that maps failures back to the criterion.
+ 2. **Tests are written before implementation** - the initial run fails on
+ every scenario, and the failing tests are the work backlog.
+ 3. **Scaffold step stubs whose bodies raise `NotImplementedError`** (or
+ `PendingException`) so nothing passes silently.
+ 4. **Emit the AC-to-test traceability table** - a 1:1 mapping of AC → test
+ → status that answers "did we test what the customer asked for?"
+ 5. **Run via the team's incumbent BDD runner** - never force a runner
+ switch alongside test-first adoption.
+ The full worked feature, stub examples, traceability artifact, per-runner
+ tag-filter commands, and ATDD-specific anti-patterns:
+ [references/atdd-traceability.md](references/atdd-traceability.md).
+
+ ## From manual test steps
+
+ When the input is an already-written manual step (table row, prose bullet,
+ TestRail / Qase / Xray exported step), the job is a declarative rewrite,
+ not a translation: strip UI mechanics ("clicks the button", "types in the
+ field"), elevate user intent ("signs in", "adds the product"), and align
+ vocabulary with the existing step library.
+
+ 1. **Classify each step**: UI mechanic / state assertion / business action
+ / setup / observation. Mechanics and assertions get rewritten; business
+ actions pass through; setup becomes `Given`; observations drop into
+ step-definition detail.
+ 2. **Apply the rewrite rules** R1-R5: remove UI mechanics, collapse
+ multi-step UI sequences into one business action, replace UI properties
+ with observable outcomes, choose the right keyword, preserve existing
+ vocabulary.
+ 3. **Emit a side-by-side table** (manual step → Gherkin step → keyword →
+ justification) so a reviewer can confirm semantic equivalence.
+ 4. **Validate**: at most one `When` per scenario; lint; specificity
+ preserved (cart count "1" stays "one item", never "non-empty").
+
+ The classification table, the full R1-R5 rule catalog with examples, and
+ migration-specific anti-patterns:
+ [references/manual-step-rules.md](references/manual-step-rules.md).
+
+ ## Extracting acceptance criteria from a raw spec
+
+ When the input is a PRD section or feature spec with no AC structure yet,
+ extract the criteria first, then feed them through the sections above.
+ Emits two interchangeable shapes: **Gherkin** (for Cucumber / Behave /
+ Reqnroll / pytest-bdd projects) or a **plain numbered list** (`AC-1`,
+ `AC-2`, … - consumable by the ATDD section and usable as commit-message
+ references, e.g. `feat: AC-3 - show toast on save`).
+
+ 1. **Tag each sentence** as Given (steady state / actor context), When
+ (action verbs: "clicks", "submits", "navigates"), or Then (asserted
+ outcomes), per the Gherkin reference.
+ 2. **Choose Scenario vs Scenario Outline** - Outline + `Examples:` for
+ boundary checks, role variants, status-code matrices.
+ 3. **Factor out Background** for truly shared state (auth, seed data,
+ navigation) - only one Background per Feature; don't over-extract
+ scenario-specific setup.
+ 4. **Validate observability of every Then.** Reject "Then the user feels
+ confident" / "Then the system is secure"; replace with concrete targets:
+ a visible `data-testid`, a response status, a header present.
+ 5. **Flag implicit Givens** (below) rather than fabricating.
+
+ Three worked examples (simple story, PRD with implicit preconditions,
+ Scenario Outline opportunity):
+ [references/spec-extraction-examples.md](references/spec-extraction-examples.md).
+
+ ## Shared discipline (all input shapes)
+
+ ### Use existing steps from the library
+
+ Per `bdd-step-library-curator`, the team has a curated step library. Use
+ existing steps where possible:
+
```gherkin
# Use existing step:
Given I am a logged-in customer
# vs (avoid):
Given I have authenticated to the system # NEW STEP - duplicates "I am a logged-in customer"
```
Before authoring a new step, search the library README.
- ## Step 5 - Flag implicit Givens
-
- Stories often imply preconditions:
-
- ```markdown
- ## Story
-
- A customer can apply a promo code.
- ```
-
- Implicit:
- - Customer must be on the checkout page (where? `/checkout`?
- `/cart`?).
- - Cart must be non-empty (otherwise no checkout).
- - Customer must be authenticated (or guest checkout supported?).
+ ### Flag implicit Givens
- Flag instead of guess:
+ Requirements often imply preconditions. Flag instead of guess:
```markdown
## ⚠ Implicit Given flags (3)
1. Where does the user enter the promo? `/checkout`? `/cart`?
2. What's the cart state? Empty? Multi-item?
3. Authentication required? Guest checkout supported?
The Gherkin Feature can't be authored without these answers.
```
- Same flag-and-ask pattern as
- `acceptance-criteria-extractor` (in the qa-shift-left plugin)
- Step 6.
-
- ## Step 6 - Validate Gherkin style
+ Flag-and-ask is the load-bearing pattern: silently picking one reading
+ produces a test suite that misses the paths the author never confirmed.
- The output should pass these style checks:
+ ### Validate Gherkin style
- - Declarative steps ("I apply a promo") not imperative ("I click
- the button with id #apply-promo-btn").
+ - Declarative steps ("I apply a promo") not imperative ("I click the button
+ with id #apply-promo-btn").
- Every Then has an observable outcome.
- - No technical leakage (DB names, internal API endpoints).
+ - No technical leakage (DB names, internal API endpoints, CSS selectors).
- ## Step 7 - Output
+ ### Output
```markdown
- ## Gherkin scenarios for `<story>`
+ ## Gherkin scenarios for `<source>`
- **Source story:** `LIN-1234` (Apply promo code at checkout)
+ **Source:** `LIN-1234` (story) | AC list | manual script | PRD section
**Implicit-precondition flags:** N
**Scenarios produced:** M
**Step library reuse:** K of M scenarios use existing steps only.
### Generated Feature
-
- (per Step 2-3)
-
### Implicit-precondition flags
-
- (per Step 5)
-
### New steps required
| Step | Why new |
|-----------------------------------------------|---------|
- | `Given promo code {code} is active` | New domain (admin promo state) |
- | `When I enter {code} in the promo input` | New element (promo input field) |
+ | `Given promo code {code} is active` | New domain (admin promo state) |
### Recommended next step
- After PM clarifies the implicit Givens (per flags above), author
- the new step definitions per
- `bdd-step-library-curator`
- conventions. Pair with the framework's runner per the team's stack
- (`cucumber-testing` / `behave-testing` / `reqnroll-testing`).
+ After the PM clarifies flagged Givens, author the new step definitions per
+ `bdd-step-library-curator` conventions and pair with the team's runner
+ (`cucumber-testing` / `behave-testing` / `reqnroll-testing`), or hand the
+ whole flow to `bdd-scenario-author`.
```
## Anti-patterns
- | Anti-pattern | Why it fails | Fix |
- |-----------------------------------------------------------------------|---------------------------------------------------------------------------|-----|
- | Fabricating implicit Givens | Tests pass for the wrong reason; PM never confirmed. | Flag-and-ask (Step 5). |
- | One Scenario per AC even when they should be Outline | Test code duplication. | Detect outline opportunities (Step 3). |
- | Not consulting the step library | Step proliferation; library bloats. | Search library first (Step 4). |
- | Imperative steps ("click button #foo") | Couples to UI; defeats BDD's value. | Declarative ("I apply a promo") (Step 6). |
- | Skipping the As-a / I-want / So-that header | Loses the value framing. | Triple at the Feature top (Step 1). |
+ | Anti-pattern | Why it fails | Fix |
+ |---|---|---|
+ | Fabricating implicit Givens | Tests pass for the wrong reason; the author never confirmed | Flag-and-ask |
+ | One Scenario per AC even when they should be an Outline | Test code duplication | Detect outline opportunities |
+ | Not consulting the step library | Step proliferation; library bloats | Search library first |
+ | Imperative steps ("click button #foo") | Couples to UI; defeats BDD's value | Declarative ("I apply a promo") |
+ | Skipping the As-a / I-want / So-that header | Loses the value framing | Triple at the Feature top |
+ | Then with a verb but no observable target ("Then save") | Not testable | Emit `data-testid` / response status / DOM state |
+ | Copy-pasted Givens across scenarios | Background extraction missed; brittle suite | One Background block for shared state |
## Limitations
- - **Story quality drives output quality.** Vague stories produce
+ - **Input quality drives output quality.** Vague stories and specs produce
vague Gherkin (or many flags).
- - **Step library dependency.** Without one, every step is "new" and
- the proliferation problem manifests.
- - **Doesn't run the tests.** This skill emits Gherkin; pair with
- the runner skills + step authoring.
+ - **Step library dependency.** Without one, every step is "new" and the
+ proliferation problem manifests.
+ - **Doesn't run the tests.** This skill emits Gherkin (plus stubs in ATDD
+ mode); pair with the runner skills or `bdd-scenario-author` for the
+ runnable artifact.
+ - **ATDD mode requires the team to write ACs first** and doesn't replace
+ lower-layer tests - unit / integration coverage is still needed for
+ non-AC logic.
## References
- - `acceptance-criteria-extractor` (in the qa-shift-left plugin) - sibling: AC-first variant.
- - `bdd-step-library-curator` - step library this skill draws from.
- - `acceptance-test-from-criteria` - sibling: ATDD-flavored variant.
+ - [references/atdd-traceability.md](references/atdd-traceability.md) - the
+ full ATDD workflow: tagged scenarios, red-first, stubs, traceability.
+ - [references/manual-step-rules.md](references/manual-step-rules.md) - the
+ manual-step classification + R1-R5 declarative-rewrite rules.
+ - [references/spec-extraction-examples.md](references/spec-extraction-examples.md) -
+ worked spec-extraction examples.
+ - Cucumber Gherkin reference (keywords, Outline + Examples, Background
+ rules): https://cucumber.io/docs/gherkin/reference
+ - Cucumber Better Gherkin (declarative vs imperative):
+ https://cucumber.io/docs/bdd/better-gherkin/
+ - ISTQB Glossary V4.7.1 - acceptance criteria
+ (https://glossary.istqb.org/en_US/term/acceptance-criteria) and ATDD
+ (https://glossary.istqb.org/en_US/term/acceptance-test-driven-development).
+ - `bdd-step-library-curator` - the step library this skill draws from.
+ - `bdd-scenario-author` - downstream agent that wires the Feature to a
+ detected runner.