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.

Install with skills.sh (any agent)

npx skills add testland/qa --skill bdd-step-library-curator

View source

bdd-step-library-curator

Overview

After 6 months of a BDD project, step definitions proliferate:

Two engineers write Given a user and Given a logged-in user for the same fixture.
Three slightly-different "I click X" steps (one for buttons, one for links, one for arbitrary elements) - all do the same thing.
A new engineer can't find existing steps and writes a fourth variant.

The result: step library bloat → Gherkin features hard to read, step ambiguities, runtime errors, drift.

This skill builds a curation workflow.

When to use

A BDD project's step count exceeds ~50 (proliferation threshold).
A new engineer reports "I couldn't find a step for X."
Quarterly: scheduled step review.
Before adopting BDD across multiple teams (proactively design the step library shape).

How to use

Work through Steps 1-6 below in order: inventory -> detect duplicates -> recommend consolidations -> reorganize and publish the README -> gate new steps pre-merge -> repeat on a cadence.

Step 1 - Inventory step definitions

Extract every declared step pattern across the project. Each runner uses its own annotation syntax (@Given in Cucumber-JVM, @given in Behave, [Given] in Reqnroll / SpecFlow) - the per-runner extraction commands are in references/step-extraction-and-overlap.md.

The inventory produces a step audit:

Total step definitions: 142
Unique patterns: 138    (4 ambiguous duplicates already)
Per Gherkin verb:
  Given: 58
  When:  34
  Then:  47
  And:    3

Step 2 - Detect duplicates / overlaps

Two patterns are likely duplicates when:

Same wording, different phrasing: Given a user vs Given an existing user vs Given the user.
Same parameters, different verbs: When I click {label} vs When I press {label} vs When I tap {label}.
Same fixture, different shape: Given a cart with {n} items vs Given a cart containing {n} items.

Normalize each pattern (lowercase, drop articles, collapse parameters) and group by the normalized form; any group of size greater than one is a candidate cluster. The overlap script that does this is in references/step-extraction-and-overlap.md.

Step 3 - Recommend consolidation

For each duplicate group:

**Duplicate group:** 4 step definitions with normalized "user is
logged in"

| Pattern                            | File / line                |
|------------------------------------|----------------------------|
| `Given a user is logged in`         | `auth_steps.py:12`         |
| `Given the user is logged in`        | `cart_steps.py:8`           |
| `Given an authenticated user`        | `checkout_steps.py:5`       |
| `Given a logged-in user`            | `profile_steps.py:14`       |

**Recommendation:** Consolidate to **`Given a logged-in user`**
(highest count of usage in current Gherkin; clearest wording).

Replace the other 3 step definitions with a single canonical one
in `shared_steps.py`. Update the Gherkin features that use the
deprecated patterns.

Verify: consolidation is destructive - it deletes step definitions and rewrites .feature files. After each group, run the full BDD suite and assert zero undefined or ambiguous steps and no orphaned scenarios before declaring the refactor complete. If a scenario reports an undefined step, a .feature file still references a deprecated pattern - fix that reference and re-run.

Step 4 - Domain organization

Group steps per domain area:

features/steps/
├── shared/                      # cross-domain (login, navigation, etc.)
│   ├── auth_steps.py
│   ├── navigation_steps.py
│   └── data_steps.py
├── checkout/                    # checkout-specific
│   ├── promo_steps.py
│   ├── payment_steps.py
│   └── cart_steps.py
├── account/                     # account-specific
│   └── profile_steps.py
└── README.md                    # step library index

The README is the discoverability artifact:

# Step library

## Shared (cross-domain)

### Auth
- `Given a logged-in user` (auth_steps.py:12) - creates and logs in a generic test user.
- `Given a logged-in admin` (auth_steps.py:25) - logged-in user with admin role.
- `Given an unauthenticated visitor` (auth_steps.py:38) - no session.

### Navigation
- `When I navigate to {path}` - go to URL.
- `When I click {label}` - click any element with this label.

## Checkout

### Cart
- `Given the cart contains {qty} of {sku} at ${price}` - seed a cart.
- `Given the cart is empty` - empty cart.

### Promo codes
- `Given promo code {code} is active` - pre-seed a promo in the admin.
- `When I enter {code} in the promo input` - type the code.
- `When I click {label}` - (uses shared step).

(...)

The README + grep is the team's "is there a step for X?" tool.

Step 5 - Pre-merge step gate

Add a CI check that flags new step definitions so no engineer adds a duplicate unknowingly. The check warns (doesn't block), forcing the author to acknowledge the new step and grep the README first. The check-new-steps.sh script is in references/step-extraction-and-overlap.md.

Step 6 - Quarterly cadence

Cadence	Trigger
Quarterly	Scheduled step library review.
New team member	Onboarding: walk the README.
Step count exceeds threshold	Triggered review.
New domain area	Add steps; update README.

Worked example

Curating a 142-step library in a mixed Behave project, end to end.

1. Inventory. The Behave extraction over features/steps/ yields the Step 1 audit: 142 step definitions, 138 unique patterns - so 4 are already ambiguous duplicates the runner would flag at match time.

2. Detect. The overlap script surfaces one cluster - the four user is logged in variants listed in Step 3's duplicate-group table.

3. Consolidate. Pick Given a logged-in user as canonical (clearest wording, most-used in current Gherkin). Move it into features/steps/shared/auth_steps.py, delete the other three definitions, and rewrite the .feature files that used the deprecated phrasings - edit the Gherkin first so no scenario is left orphaned, then run the Step 3 verification.

4. Reorganize + publish. Split the flat features/steps/ into shared/, checkout/, and account/, then regenerate the README index. The library now advertises Given a logged-in user (auth_steps.py) - creates and logs in a generic test user under Shared → Auth.

5. Gate. Add the pre-merge new-step check. The next PR that adds Given the customer is signed in trips the warning; the author greps the README, finds Given a logged-in user, and reuses it instead of adding a fifth variant.

Result: 142 → 139 step definitions, zero ambiguous duplicates, one discoverable index the whole team searches before writing a step.

Anti-patterns

Anti-pattern	Why it fails	Fix
Per-engineer step files (`alice_steps.py`)	Ownership without domain alignment; duplication across files.	Domain-organized files (Step 4).
Step library README missing	Discoverability nil; engineers re-implement.	README per Step 4.
Ambiguous step deletion without grep	Breaks scenarios silently.	Replace canonical → deprecated; update all Gherkin first.
Step "shared library" that's a giant `helpers.py`	All engineers conflict on it; merge hell.	Domain split (Step 4).
Reviewing step count quarterly only	Proliferation outpaces review; library bloats.	Pre-merge gate (Step 5).

Limitations

Heuristic duplicate detection. Some patterns are legitimately distinct (Given a user for auth vs Given a user with profile data for profile tests).
Domain organization is per-team. What's "shared" varies.
Consolidation cost. Each refactor touches Gherkin + step definitions; not free.
Doesn't fix Gherkin quality. A clean step library doesn't prevent imperative-style Gherkin scenarios. Pair with a Gherkin style review.

References

Step extraction commands, the overlap-detection script, and the pre-merge gate: references/step-extraction-and-overlap.md.
cucumber-testing, behave-testing, reqnroll-testing - per-language runners this curator works alongside.

Step extraction, overlap detection, and the pre-merge gate

View source

Step extraction, overlap detection, and the pre-merge gate

Deep reference for the bdd-step-library-curator SKILL. Consult when running the inventory against a specific BDD runner, wiring the programmatic overlap detector, or adding the pre-merge new-step CI gate.

Per-runner step extraction

Each BDD runner declares steps with its own annotation syntax; extract the raw patterns per runner and combine the output into a single list.

# Cucumber-JVM
grep -rE '@(Given|When|Then|And|But)\(' src/test/java/ | \
  sed -E 's/.*@(Given|When|Then|And|But)\("([^"]*)".*/\2/'

# Behave
grep -rE '^@(given|when|then|step)\(' features/steps/ | \
  sed -E 's/.*@(given|when|then|step)\("([^"]*)".*/\2/'

# Reqnroll / SpecFlow
grep -rE '\[(Given|When|Then|And|But)\(' Tests/Steps/ | \
  sed -E 's/.*\[(Given|When|Then|And|But)\("([^"]*)".*/\2/'

Each command emits one step pattern per line; feed the combined list into the overlap detector below.

Programmatic overlap detection

Normalize each pattern (lowercase, strip articles, collapse every parameter to a single placeholder) and group patterns that collapse to the same normalized form. Any group of size greater than one is a candidate duplicate cluster.

# scripts/step-overlap.py
import re

def normalize(pattern):
    """Lower; strip articles; remove parameter type hints."""
    p = pattern.lower()
    p = re.sub(r'\b(a|an|the)\b', '', p)
    p = re.sub(r'\{[^}]+\}', '{var}', p)
    p = re.sub(r'\s+', ' ', p).strip()
    return p

steps = [...]   # from the extraction step

normalized = {}
for s in steps:
    n = normalize(s['pattern'])
    normalized.setdefault(n, []).append(s)

for n, group in normalized.items():
    if len(group) > 1:
        print(f"Likely duplicates ({len(group)}):")
        for s in group:
            print(f"  {s['pattern']} - {s['file']}:{s['line']}")

The detector is a heuristic - review each cluster before consolidating, since some collisions are legitimately distinct steps.

Pre-merge new-step gate

A CI check that warns (does not block) whenever a PR adds new step definitions, forcing the author to confirm the step is not already in the library.

# scripts/check-new-steps.sh
NEW_STEPS=$(git diff --diff-filter=A origin/main...HEAD -- '**/steps/*.py' '**/Steps/*.cs' '**/steps/*.java' \
  | grep -E '^\+' | grep -E '@(Given|When|Then)' | wc -l)

if [ $NEW_STEPS -gt 0 ]; then
  echo "::warning::This PR adds $NEW_STEPS new step definitions."
  echo "Before merging, verify these aren't duplicates of existing steps."
  echo "Run: bash scripts/step-overlap.py"
fi

The warning is intentionally non-blocking - it forces acknowledgment of a new step without stopping legitimately-new ones.

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.

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.

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.

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.