gherkin-from-stories

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.

Install with skills.sh (any agent)

npx skills add testland/qa --skill gherkin-from-stories

View source

gherkin-from-stories

Overview

The shift-left flow:

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).

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.

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.

Step 1 - Extract the user-story triple

# 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:

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:

## Acceptance criteria

- 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."

Each AC becomes a Scenario:

  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

Multiple ACs that vary only in input data become a Scenario Outline:

  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."

Step 4 - Use existing steps from the library

Per bdd-step-library-curator, the team has a curated step library. Use existing steps where possible:

# 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:

## 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 instead of guess:

## ⚠ 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

The output should pass these style checks:

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).

Step 7 - Output

## Gherkin scenarios for `<story>`

**Source story:** `LIN-1234` (Apply promo code at checkout)
**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) |

### 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`).

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).

Limitations

Story quality drives output quality. Vague stories 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.

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.

Related skills

acceptance-test-from-criteria

ATDD (Acceptance Test-Driven Development) workflow that generates @AC-N-tagged Gherkin scenarios from a signed-off acceptance-criteria list, scaffolds NotImplementedError step stubs, and produces an AC-to-test traceability table, all before implementation begins, in the team's BDD framework (Cucumber / Behave / Reqnroll). Use when devs are gated on green acceptance tests and failures must map back to a specific criterion. For story-narrative-to-Gherkin without prior ACs, use gherkin-from-stories. For BDD scenario authoring without the ATDD test-first gate, use a general BDD scenario-authoring workflow.

bdd-overview

Teaches behaviour-driven development end to end for a newcomer: what BDD is and how discovery, formulation and automation fit together; a decision table that picks the runner from the project's language and build files (Cucumber-JVM, Cucumber-JS, Cucumber-Ruby, Behave for Python, Reqnroll for .NET, and why SpecFlow is end-of-life); install and first-run commands for each; the declarative-versus-imperative Gherkin discipline with a worked bad-versus-good pair; Background, Scenario Outline and domain-organised step libraries; the traps that make BDD collapse into an expensive UI-automation wrapper; and an honest account of when BDD is not worth adopting. Use when a team is adopting BDD, choosing a Gherkin runner, or a *.feature file needs writing and nobody has settled the conventions.

bdd-step-library-curator

Keeps a BDD step-definition library DRY across a Cucumber / Behave / Reqnroll project - inventories every step definition, detects duplicates (different patterns matching the same intent), recommends canonical consolidations, reorganizes steps by domain, and publishes a step-library README the team greps for "is there already a step for X?" before authoring new ones. Use when a BDD project's step count grows past ~50, on a quarterly step-library review, or when a new engineer cannot find an existing step and is about to write a duplicate.

behave-testing

Configures Behave for Python BDD scenarios - `pip install behave`, authors `.feature` files in Gherkin, writes step implementations in `features/steps/*.py`, configures via `environment.py` for setup/teardown hooks, organizes via tags, runs via `behave`. Use for Python codebases that want Cucumber-family BDD without Cucumber-Ruby / Cucumber-JS.

cucumber-testing

Configures Cucumber for BDD scenarios - Cucumber-JVM (Java/Kotlin via JUnit 5), Cucumber-JS (Node), Cucumber-Ruby. Authors `.feature` files in Gherkin, writes step definitions in the host language, runs via the framework's runner, integrates with JUnit XML reporting. Use when the user mentions Cucumber, Gherkin, `.feature` files, or behavior-driven (BDD) tests in Java, Kotlin, JavaScript, or Ruby, as the canonical wrapper for any of the three official implementations.

living-documentation-publisher

Converts passing Cucumber JSON output into stakeholder-facing living documentation: generates HTML reports via multiple-cucumber-html-reporter (Node) or Serenity BDD aggregate (JVM), applies Gherkin tags to drive report sections, and publishes to GitHub/GitLab Pages in CI. Use when BDD scenarios are in use and the team needs an always-current, non-test-engineer-readable document showing which acceptance criteria pass.

manual-step-to-gherkin

Translates an existing manual test step (table row, prose bullet, TestRail/Qase exported step) into a declarative Gherkin Given/When/Then step phrased in business language - strips UI mechanics ("clicks the button", "types in the field"), elevates the user intent ("signs in", "adds the product"), and aligns vocabulary with the project's existing step library. The input is an already-written manual step - not a user story and not an acceptance-criteria list. Use when a team is migrating manual test scripts to BDD, or when a manual tester is handing a script off to an automation engineer.

reqnroll-testing

Configures Reqnroll (the canonical .NET BDD framework) - install via `dotnet add package Reqnroll`, author `.feature` files in Gherkin, write step bindings as `[Given/When/Then]`-decorated methods in any C# class, runs via `dotnet test`. Reqnroll is the SpecFlow successor (originated as a community port off the SpecFlow codebase); new .NET BDD work targets Reqnroll. Use for .NET projects starting BDD or migrating from SpecFlow.

specflow-testing

Maintains SpecFlow tests on existing .NET projects - authors Gherkin `.feature` files, writes C# `[Binding]` step definitions, runs them via xUnit/NUnit/MsTest, and migrates a project to Reqnroll. SpecFlow is the legacy .NET BDD framework and Reqnroll is its maintained fork. Use only for existing SpecFlow projects, especially mid-migration; new .NET BDD projects use `reqnroll-testing` instead.