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
- Read the source spec/EPIC; confirm it is ready (clarity-gate passed) before writing.
- Write
.feature files under tests/features/ (or the project's path), named
<capability>.feature, one file per coherent business capability.
- Write in business language — no SQL, API paths, or class names; only business concepts.
- 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 |
- Cover edge cases explicitly, sourced from the spec's test-case table and error matrix.
- Fabricate sample/test data only where real examples are insufficient; place it in the
project's fixtures location.
Quality checks (before finishing)
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.
1---2name: bdd-gherkin3description: Write BDD Gherkin feature files and fabricate test data from a specification. Use to project a use case catalogue (Cockburn White/Blue) or turn acceptance criteria or an EPIC into business-language `.feature` scenarios — Scenario Outline with Examples, explicit edge cases, no implementation detail, traced back to use cases. Trigger on "write Gherkin", "write feature files", "BDD scenarios for this acceptance criterion", "derive scenarios from use cases", "fabricate test data".4license: Apache 2.05---67# BDD / Gherkin Authoring89## Overview1011Translate a specification into precise, business-language Gherkin features that define12**what** the system should do in observable, testable terms — not **how**. This is a13**design-phase** activity: the `.feature` files are a **PLAN artifact** authored alongside the14PLAN so `clarity-gate` can score scenario coverage. **Step definitions and production code are NOT15authored here** — they belong to the implement phase (`superpowers:test-driven-development`).16Scenario *thinking* (what to prove, which edge cases) is elicited in `epic-planning`'s interview.1718**Where a use case catalogue exists, it is the source, not the EPIC directly.** When the architecture19defines White/Blue use cases (Cockburn — see the `architecture` skill), Gherkin is the **executable20projection** of those use cases, not an independent second spec. Derive scenarios from a UC's Main21Success Scenario, Alternate Scenarios, and Extensions (mapping table in the `architecture` skill's22`use-cases-cockburn.md`); prefer the Blue refinement, which names concrete error codes and boundaries.23Gherkin **adds data, not behaviour**: concrete `Examples:`, boundary values, and edge-case rows that24the UC states abstractly. It **invents no behaviour absent from a use case** — a scenario with nothing25to trace back to is a catalogue gap; fix the UC first, then project. Where no catalogue exists, fall26back to the EPIC acceptance criteria and test-case/error tables.2728## Quick Start29301. Read the source spec/EPIC; confirm it is ready (clarity-gate passed) before writing.312. Write `.feature` files under `tests/features/` (or the project's path), named32 `<capability>.feature`, one file per coherent business capability.333. Write in **business language** — no SQL, API paths, or class names; only business concepts.344. Prefer **`Scenario Outline` + `Examples:`** for data-driven coverage:3536```gherkin37Scenario Outline: <description>38 Given <precondition>39 When <action with parameter>40 Then <expected outcome>4142 Examples:43 | parameter | expected |44 | value1 | result1 |45 | value2 | result2 |46```47485. Cover edge cases **explicitly**, sourced from the spec's test-case table and error matrix.496. Fabricate sample/test data only where real examples are insufficient; place it in the50 project's fixtures location.5152## Quality checks (before finishing)5354- [ ] Every task in the breakdown has feature coverage.55- [ ] **Where a UC catalogue exists:** every UC Main Success Scenario, Alternate Scenario, and56 Extension has ≥1 scenario, and every scenario traces back to a UC id (`UC-W1`, `UC-B1.1`) — no57 untraceable, invented behaviour.58- [ ] Every test-case-spec row and every error-matrix row has a scenario.59- [ ] `Scenario Outline` used wherever multiple data variations apply.60- [ ] No implementation details leak in (no SQL / API paths / class names).61- [ ] Files are syntactically valid Gherkin.6263## Boundary & Related Skills6465**Owns:** feature files + test data. **Does NOT** write step definitions or production code66(that is the implementer's job, following `cosmic-python` + `superpowers:test-driven-development`),67and does NOT plan (`epic-planning`) or score specs (`clarity-gate`).68**Related:** `architecture` (the White/Blue use case catalogue Gherkin projects from), `epic-planning`,69`clarity-gate`, `spec-stewardship`, `cosmic-python`.
meaningfy-ws