bdd-gherkin

BDD / Gherkin Authoring

Overview

Translate a specification into precise, business-language Gherkin features that define what the system should do in observable, testable terms — not how. This is a design-phase activity: the .feature files are a PLAN artifact authored alongside the PLAN so clarity-gate can score scenario coverage. Step definitions and production code are NOT authored here — they belong to the implement phase (superpowers:test-driven-development). Scenario thinking (what to prove, which edge cases) is elicited in epic-planning's interview.

Where a use case catalogue exists, it is the source, not the EPIC directly. When the architecture defines White/Blue use cases (Cockburn — see the architecture skill), Gherkin is the executable projection of those use cases, not an independent second spec. Derive scenarios from a UC's Main Success Scenario, Alternate Scenarios, and Extensions (mapping table in the architecture skill's use-cases-cockburn.md); prefer the Blue refinement, which names concrete error codes and boundaries. Gherkin adds data, not behaviour: concrete Examples:, boundary values, and edge-case rows that the UC states abstractly. It invents no behaviour absent from a use case — a scenario with nothing to trace back to is a catalogue gap; fix the UC first, then project. Where no catalogue exists, fall back to the EPIC acceptance criteria and test-case/error tables.

Quick Start

1. Read the source spec/EPIC; confirm it is ready (clarity-gate passed) before writing.
2. Write .feature files under tests/features/ (or the project's path), named <capability>.feature, one file per coherent business capability.
3. Write in business language — no SQL, API paths, or class names; only business concepts.
4. Prefer Scenario Outline + Examples: for data-driven coverage:

Scenario Outline: <description>
  Given <precondition>
  When <action with parameter>
  Then <expected outcome>

  Examples:
    | parameter | expected |
    | value1    | result1  |
    | value2    | result2  |

5. Cover edge cases explicitly, sourced from the spec's test-case table and error matrix.
6. Fabricate sample/test data only where real examples are insufficient; place it in the project's fixtures location.

Quality checks (before finishing)

• Every task in the breakdown has feature coverage.
• Where a UC catalogue exists: every UC Main Success Scenario, Alternate Scenario, and Extension has ≥1 scenario, and every scenario traces back to a UC id (UC-W1, UC-B1.1) — no untraceable, invented behaviour.
• Every test-case-spec row and every error-matrix row has a scenario.
• Scenario Outline used wherever multiple data variations apply.
• No implementation details leak in (no SQL / API paths / class names).
• Files are syntactically valid Gherkin.

Boundary & Related Skills

Owns: feature files + test data. Does NOT write step definitions or production code (that is the implementer's job, following cosmic-python + superpowers:test-driven-development), and does NOT plan (epic-planning) or score specs (clarity-gate). Related: architecture (the White/Blue use case catalogue Gherkin projects from), epic-planning, clarity-gate, spec-stewardship, cosmic-python.