gherkin_scenario_writing v1.0.0

name: gherkin_scenario_writing description: "Write and review Gherkin acceptance scenarios that stay readable: Feature and Rule structure, Given-When-Then discipline, declarative style, Scenario Outline and Examples tables, Data Tables and Doc Strings, the anti-patterns that turn scenarios into scripts, and a health check for deciding whether a BDD suite is worth keeping. Use when writing or reviewing .feature files, acceptance criteria, or Cucumber, Behave, or SpecFlow style specs."

Gherkin Scenario Writing

Purpose

Write Gherkin that works as living documentation first and as tests second. A good scenario states one business rule in words a non-developer can read, survives a redesign of the screens or endpoints behind it, and fails for one clear reason when the rule breaks. This skill covers the writing craft only. Step definition code and runner setup belong to the project test skill, not here.

Workflow

1. Start from the rule, not the flow. Name the business rule the scenario illustrates before writing any steps. Get rules and concrete examples from a conversation with the people who own the behaviour, in the Discovery, Formulation, Automation order the Cucumber team describes: agree examples together, write them in business terms, then automate. One scenario illustrates one rule. If you cannot state the rule in one sentence, you do not have a scenario yet.

1. Structure the file. One Feature per .feature file, and Feature is the first keyword. Add a short free-form description under Feature that states who gains what. Group scenarios under Rule (available since Gherkin 6) when a feature carries several rules. Use Background only for Given steps every scenario in the Feature or Rule truly shares, keep it to four steps or fewer, and use vivid names instead of labels like User A. Put tags above Feature, Rule, or Scenario, never on Background or steps.

1. Write steps with strict role discipline. Given states a known starting state, in past or state terms, with no user interaction in it. When states the single event or action, from a person or from another system. Then states an observable outcome, something a user or caller receives, sees, or can do next, checked with an assertion in the step definition. Use And and But to continue the previous step type, and use * only for a plain list of similar items. Keep most scenarios to three to five steps, and most to five lines or fewer where the team follows the BRIEF guidance from Cucumber (Business language, Real data, Intention revealing, Essential, Focused, Brief).

1. Write declaratively. Describe what happens, not how it happens on screen or over the wire. Apply the test from the Cucumber guide: if the wording would need to change when the implementation changes, rework it. Clicks, field names, URLs, selectors, waits, status codes, and table row counts live in step definitions, not in steps. The one exception is a feature whose contract really is an API or a protocol, and then the Feature description should say so.

1. Pick the right container for data. Plain Scenario for one concrete example. Scenario Outline with an Examples table when the same rule gives different outcomes for different inputs and each row should fail on its own: parameters use angle brackets, steps run once per row, and the header row names the parameters. Keep tables narrow, only columns that change the outcome. Attach a Data Table to a step for a set of structured records, and a Doc String for a block of exact text. Never use an outline with a single row, and never fold different rules into one outline to save lines. Escape pipe as \|, newline as \n, and backslash as \\ inside table cells.

1. Check your own draft against the anti-pattern list. Work through references/anti-patterns.md: UI script, two behaviours in one scenario, conjunctive When steps, incidental detail, Then steps that inspect internal storage, swollen Background, outline misuse, duplicate step text under different keywords, vague data, and scenarios copied from finished code. Step matching ignores the keyword, so the same sentence under Given and Then collides: reword context and outcome so they read differently.

1. Run the checker and fix what it flags. Run python3 bin/check_gherkin.py <file.feature> from this skill directory, or pass several files at once, add --json for machine readable output. The checker counts steps per scenario, flags a second When after a Then, flags imperative wording and non-observable Then steps, warns on Background over four steps, generic titles, duplicate step text, and outlines with zero or one Examples rows. It is a review aid, not a parser: still run the project Cucumber dry run to prove the file parses and every step has a definition.

1. Work an example before inventing one. Read references/worked-examples.md and examples/good.feature for the pattern, and examples/bad.feature for a file the checker flags on purpose. Copy the structure, change the domain, keep the discipline.

1. Run the suite health check before adding more scenarios. Score the suite in the Output Contract below. A suite that fails the health check gets pruned or rewritten first. Adding fresh scenarios to a suite nobody reads grows the maintenance bill and teaches the team to ignore failures.

Output Contract

For a writing task, deliver:

1. The .feature file or files, ready to parse, with Feature description, Rule grouping where it helps, and tags only where they select a real subset or mark real state.
2. A short rewrite table for any scenario you changed: original problem, in the words of references/anti-patterns.md, and what you changed.
3. Checker output for every file delivered, plus the result of the project parser or dry run when one is available. State plainly when no runner was available to test with.

For a suite health check, deliver a verdict of keep, prune, or rewrite, backed by these five measures, each with the count you actually observed:

1. Readability: share of scenarios over five steps, and share with imperative wording from the checker.
2. Focus: share of scenarios with more than one When block.
3. Duplication: scenarios that repeat the same behaviour, and step text reused under different keywords.
4. Failure signal: in the last run history the team can show, how many red scenarios pointed at a real rule break, and how many were wording, data, or environment noise. Use the team records, do not estimate this one.
5. Ownership: every feature file has a named owner who still works on that area, and a review cadence. Unowned files count against the suite.

Starting points a team can adopt and adjust: prune or rewrite when more than a third of scenarios flag imperative wording, when any feature file has no owner, or when most red runs in the recent history were noise. Label these thresholds as team choices in the report, not as published standards. Recommend keeping the suite only when it is read by the people who own the behaviour and its failures change decisions.

Operating Rules

1. Every factual claim about Gherkin syntax or Cucumber guidance in a delivered skill or report must trace to the Cucumber reference, the Cucumber better Gherkin guide, the Cucumber BRIEF post, or another primary source named in the work. Unverifiable claims get cut or labelled as team practice.
2. Never invent a rule, limit, or date. The numbers used here are sourced: three to five steps per example and Background kept short with four lines as the warning point come from the Cucumber reference, five lines or fewer for most scenarios comes from the BRIEF post.
3. Write scenarios before or with the code, from agreed examples. A scenario copied from finished screens documents the build, not the agreement.
4. Keep real data concrete and safe: named people, exact amounts, and specific products are good, real customer data, real credentials, and real personal details never belong in a feature file.
5. Do not half publish a feature file: no placeholder steps, no empty scenarios, no outline without Examples rows. A file that fails the checker with errors, or that no runner has parsed, gets fixed before it ships or it does not ship.
6. Keep the language of the file the language the domain experts speak. Gherkin supports many spoken languages through a language header on the first line: use it instead of translating terms badly into English.

Sources

• Cucumber Gherkin Reference: https://cucumber.io/docs/gherkin/reference/
• Cucumber, Writing better Gherkin: https://cucumber.io/docs/bdd/better-gherkin/
• Cucumber blog, Keep your scenarios BRIEF, 2019: https://cucumber.io/blog/bdd/keep-your-scenarios-brief/
• Automation Panda, BDD 101, Writing Good Gherkin, 2017: https://automationpanda.com/2017/01/30/bdd-101-writing-good-gherkin/