Chapter 9: A new user story
The chapter introduces a pay-on-collection requirement that the team will use as it formulates examples into scenarios.
After this chapter you will be able to
- Restricted Customer Requirement. Explain the business problem behind the new story and the proposed restriction on pay-on-collection.
- Outcome-first scenario formulation. Explain how writing a scenario from its outcome backward helps the team decide which context statements are essential.
- Collaborative formulation challenge. Explain how the different proposed outcomes for the pay-on-collection example illustrate the difficulty of writing collaboratively. State that the section raises, but does not answer, who should formulate examples uncovered during discovery.
- Separate discovery and formulation. Explain why a team should capture concrete examples during discovery rather than formulate them at the same time.
- Delegated scenario formulation. Explain why a subset of the team may write scenarios even though the scenarios use a shared language and remain collectively owned.
- Meaningful team scenario review. Describe the review needed to make delegated formulation work, including who should accept scenarios before work begins on a story.
- Shared formulation and specification responsibility. Explain why delivery-team members write scenarios for PO/BA review, and distinguish shared formulation work from PO/BA responsibility for the specifications.
- Scenario writing for delivery teams. Explain why writing scenarios is a valuable use of developers’ and testers’ time: it helps them confirm their understanding of business requirements and terminology so they can make appropriate decisions.
- Complementary formulation pair. Explain why the authors favor a pair over one person for formulation, and describe the perspectives the pair should bring.
- Cross-disciplinary scenario review. Explain what review is needed after formulation has been delegated.
- Shared formulation and feedback. Explain why the same people should not always formulate specifications, and describe how the team can choose formulators and review their work.
- Scenario readability over quotes. Justify removing quotation marks from scenario terms when they reduce readability, even if the marks indicate terms with a specific meaning in the system.
- Unambiguous scenario actors. Explain why first-person “I” can make a scenario imprecise and why the section recommends identifying actors by role or persona in the third person.
- Clear References to Actors. Explain when replacing a repeated actor name with “they” makes a scenario more natural, and when repeating the name is clearer.
- Readability Over Automation Convenience. Justify keeping scenario wording business-readable even if pronouns make automation more complex.
- Shared context in Backgrounds. Explain that a Gherkin Background supplies context steps for every scenario in a feature or rule, without changing the scenarios’ behavior when shared steps are moved into it.
- Readability over removed repetition. Justify caution when using Backgrounds: eliminating repeated steps may make scenarios less readable and harder to maintain, so simple, explicit wording can be preferable.
- Selecting examples for scenarios. Explain why examples from example mapping can be changed, merged, or left unformulated when writing scenarios, using the two customer scenarios as an illustration.
- Purposeful explanatory text. Distinguish when to use a comment or a text description, and explain why either should be used sparingly.
- Implicit and exceptional context. Explain when a scenario can leave context unstated and when it should state it explicitly, using the pay-on-collection or kettle examples.
- Focus on the restriction rule. Explain why a scenario about whether a customer is restricted should not also try to define how email addresses and phone numbers are matched.
- Consistent scenario phrasing. Explain why the first scenarios take longer to formulate and how later, similar scenarios become quicker.
- Readability before step reuse. Justify why a team should favor consistent, readable scenario steps over making steps maximally reusable.
- Low to high fidelity delivery. Explain how small increments can begin with a low-fidelity implementation and build toward functionality suitable for release, while allowing the team to get feedback before all the work is done.
- Intent-focused evolving scenarios. Describe why a high-level scenario can state the intended behavior without fixing technical details, and how that scenario can remain useful as implementation and automation change.
- Purpose of Gherkin tags. Explain what a Gherkin tag documents, why it should be business-readable, and how it can affect scenario automation.
- Manual scenario trade-off. Explain why the team marks a scenario @manual and what risk comes with leaving scenarios unautomated.
- Timing of scenario review. Explain why scenarios should ideally be reviewed as soon as they are formulated, before automation or production code begins, while recognizing that some teams start implementation before review is complete.
- Team review and product accountability. Describe why the whole team should review formulated scenarios, especially the first ones in a new functional area, and state the PO’s minimum review responsibility.
What it builds on
- Keeping context essential (chapter 8) · The distinction between essential and unnecessary scenario context.
- Collecting examples (chapter 2) · Discovery produces examples that can subsequently be formulated.
- Shared understanding (chapter 6) · The aim of shared understanding in formulation.
- Scenario structure (chapter 8) · Assumes familiarity with a scenario’s Given, When, and Then structure.
- Gherkin basics (chapter 8) · Introduces Gherkin as the format used to express scenarios.
- Living documentation (chapter 6) · Introduces scenarios as living documentation.
- Rules (chapter 8) · The distinction between features and rules in a Gherkin feature file.
- Scenarios should read like a specification (chapter 7) · The aim of making scenarios readable as specifications.
Section by section
Introduction
The chapter introduces a pay-on-collection requirement that the team will use as it formulates examples into scenarios.
- Restricted Customer Requirement: Explain the business problem behind the new story and the proposed restriction on pay-on-collection.
Why it matters: This requirement gives the team a concrete behavior to specify in the chapter.
Key terms: pay-on-collection, restricted customers
9.1 Write it upwards
The section introduces “write it upwards”: formulate a scenario from its outcome backward so each part has a clear causal connection and unnecessary context can be removed.
- Outcome-first scenario formulation: Explain how writing a scenario from its outcome backward helps the team decide which context statements are essential.
Why it matters: It helps keep scenarios focused rather than filling them with context that does not explain the outcome.
Key terms: write it upwards, outcome, context statements, causal connection
9.2 Too many cooks
This section illustrates why collaboratively wording a discovered example can be difficult, then raises questions about who should formulate it.
- Collaborative formulation challenge: Explain how the different proposed outcomes for the pay-on-collection example illustrate the difficulty of writing collaboratively. State that the section raises, but does not answer, who should formulate examples uncovered during discovery.
Why it matters: The differing suggestions show why deciding how to formulate examples takes care.
Key terms: formulating, concrete examples, discovery, expected outcome
9.2.1 Why not formulate during the discovery session?
This section explains why discovery and formulation should be separate practices.
- Separate discovery and formulation: Explain why a team should capture concrete examples during discovery rather than formulate them at the same time.
Why it matters: Keeping examples quick to capture gives the whole team room to discuss what the system should do.
Key terms: discovery, concrete examples, shared understanding, formulation
9.2.2 Shouldn’t the whole team formulate together?
This section explains why a subset of the team can formulate scenarios, provided the whole team reviews and owns them.
- Delegated scenario formulation: Explain why a subset of the team may write scenarios even though the scenarios use a shared language and remain collectively owned.
Why it matters: A small drafting group need not exclude the rest of the team from shaping the scenarios. - Meaningful team scenario review: Describe the review needed to make delegated formulation work, including who should accept scenarios before work begins on a story.
Why it matters: Delegation works only when review is a real opportunity to catch unclear scenarios, not a formality.
Key terms: formulation, shared language, ubiquitous language, collective ownership, asynchronous reviewing, constructive feedback, reviewed and accepted, product owner, delivery team
9.2.3 Don’t the product owners (POs)/business analysts (BAs) own the specifications?
The section explains how PO/BA review of scenarios written by the delivery team confirms shared understanding while leaving specification responsibility with the PO/BA.
- Shared formulation and specification responsibility: Explain why delivery-team members write scenarios for PO/BA review, and distinguish shared formulation work from PO/BA responsibility for the specifications.
Why it matters: This division of work helps the team check that business knowledge has been understood before it guides development and testing.
Key terms: PO/BA, delivery team, scenarios, concrete examples, business terminology, shared understanding
9.2.4 Shouldn’t the developers/testers focus on the implementation?
This subsection explains why developers and testers should help write scenarios rather than focus only on implementation.
- Scenario writing for delivery teams: Explain why writing scenarios is a valuable use of developers’ and testers’ time: it helps them confirm their understanding of business requirements and terminology so they can make appropriate decisions.
Why it matters: Scenario writing helps the people delivering the software check that they understand what the business needs.
Key terms: business context, business requirements, business terminology, scenarios
9.2.5 Isn’t it more efficient for one person to do it?
Formulation benefits from a pair with complementary perspectives, followed by detailed review of the scenarios by other disciplines.
- Complementary formulation pair: Explain why the authors favor a pair over one person for formulation, and describe the perspectives the pair should bring.
Why it matters: A small formulation group can work efficiently without relying on just one point of view. - Cross-disciplinary scenario review: Explain what review is needed after formulation has been delegated.
Why it matters: Delegating formulation does not remove the need for input from the wider team.
Key terms: formulation, business perspective, technical perspective, scenarios, other disciplines
9.2.6 Should the same people always do the formulation?
The section explains why formulation should be shared across the team and how choosing formulators and reviewing their work supports learning.
- Shared formulation and feedback: Explain why the same people should not always formulate specifications, and describe how the team can choose formulators and review their work.
Why it matters: Sharing the work gives more team members a chance to clarify the behavior before misunderstandings persist in the specification.
Key terms: formulation, shared ownership, specification, constructive feedback
9.3 Quotation marks
The section explains why quotation marks in scenarios offer little automation benefit when they make the text harder to read.
- Scenario readability over quotes: Justify removing quotation marks from scenario terms when they reduce readability, even if the marks indicate terms with a specific meaning in the system.
Why it matters: Readable scenarios remain useful to the people who return to them after automation. - Quoted text in generated snippets: Explain how scenario automation tools treat quoted text when generating step definition snippets and why that feature offers limited benefit.
Why it matters: This explains why generated snippets are not, by themselves, a strong reason to add quotes.
Key terms: quotation marks, readability, scenario, step definition snippets, scenario automation tools
9.4 There’s no “I” in “Persona”
This section explains how to name actors unambiguously in scenarios, when to use a role instead of a persona, and how step wording conveys sequence and expected outcomes.
- Unambiguous scenario actors: Explain why first-person “I” can make a scenario imprecise and why the section recommends identifying actors by role or persona in the third person.
Why it matters: Clear actor names help everyone read the same scenario the same way. - Role versus persona choice: Justify using a descriptive role such as “customer” rather than creating a persona solely for this scenario.
Why it matters: A clear role can remove ambiguity without making readers learn an unnecessary persona. - Step wording and sequence: Describe what the section says the Given, When, and Then wording conveys in the revised scenario.
Why it matters: These wording choices help a reader distinguish what happened before, what action occurs, and what outcome is expected.
Key terms: first person “I”, third person, role, persona, role description, customer, Given, When, Then, past tense
9.5 Does repetition matter?
This section explains how to choose between repeated names and pronouns in scenarios while preserving readability, clarity, and the integrity of an approved specification.
- Clear References to Actors: Explain when replacing a repeated actor name with “they” makes a scenario more natural, and when repeating the name is clearer.
Why it matters: A natural-sounding scenario is useful only if readers can still tell who does what. - Readability Over Automation Convenience: Justify keeping scenario wording business-readable even if pronouns make automation more complex.
Why it matters: The specification remains useful to business readers rather than being shaped around tool limitations. - Stability of Approved Scenarios: Explain why a team should leave an approved, formulated scenario unchanged unless the system’s behavior changes.
Why it matters: Treating approved scenarios as specifications discourages casual edits after the team has agreed on them.
Key terms: they, repetition, pronoun, readability, business-readable, Gherkin, automation framework, linguistic shortcuts, formulated scenario, reviewed and approved
9.6 Moving shared context into a background
This section explains how Gherkin Backgrounds share scenario context and why removing repetition can make scenarios harder to read and maintain.
- Shared context in Backgrounds: Explain that a Gherkin Background supplies context steps for every scenario in a feature or rule, without changing the scenarios’ behavior when shared steps are moved into it.
Why it matters: This lets you recognize what a Background does before deciding whether it improves the specification. - Readability over removed repetition: Justify caution when using Backgrounds: eliminating repeated steps may make scenarios less readable and harder to maintain, so simple, explicit wording can be preferable.
Why it matters: A little repetition may be worth keeping when it makes each scenario easier to understand and edit safely.
Key terms: Background, shared context, feature, rule, DRY, DAMP, readability, maintenance
9.7 Unformulated examples
The section explains why examples collected during discovery may be combined or left out of the formulated specification without losing their value.
- Selecting examples for scenarios: Explain why examples from example mapping can be changed, merged, or left unformulated when writing scenarios, using the two customer scenarios as an illustration.
Why it matters: It keeps discovery moving while allowing the resulting specification to focus on meaningful behavior. - Value of unformulated examples: Describe how an example can remain useful even if it does not become a scenario, and distinguish a programmer test from a scenario in this section.
Why it matters: Leaving an example out of the specification does not mean the discussion or the example was wasted.
Key terms: concrete examples, example mapping, formulation, scenario, specification, unformulated examples, programmer tests, scenarios
9.8 Commenting in feature files
Explains how Gherkin comments and text descriptions work, when to use each, and why feature files should rarely need either.
- Gherkin line comments: Explain how to write a Gherkin line comment and what scenario automation tools do with it.
Why it matters: You can leave a note without making it part of the automated scenario. - Gherkin text descriptions: Describe where plain text descriptions can appear in a feature file and how automation treats them.
Why it matters: A description can add explanatory text without becoming an automated step. - Purposeful explanatory text: Distinguish when to use a comment or a text description, and explain why either should be used sparingly.
Why it matters: Choosing the right form—and removing unnecessary explanations—keeps feature files useful to stakeholders.
Key terms: line comment, block comments, #, textual descriptions, block keyword, Gherkin keyword, tag, comments, text descriptions, feature files
9.9 Setting the context
This section shows how to keep scenarios brief and clear by leaving ordinary context implicit, stating exceptional context, and comparing alternative wordings when the team disagrees.
- Implicit and exceptional context: Explain when a scenario can leave context unstated and when it should state it explicitly, using the pay-on-collection or kettle examples.
Why it matters: Readers can spot what makes a scenario interesting without repeatedly parsing ordinary setup. - Comparing scenario wordings: Describe how a team can resolve disagreement about which context or steps are essential by writing and comparing alternative scenarios.
Why it matters: Comparing concrete alternatives helps the team make a constructive choice instead of debating wording in the abstract.
Key terms: implicit context, Given steps, restricted customer, BRIEF principles, write it upwards, essential context
9.10 Stay focused on illustrating the rule
This section shows how to formulate a concise blocklist scenario that illustrates the customer-restriction rule without also specifying unresolved email and phone matching rules.
- Focus on the restriction rule: Explain why a scenario about whether a customer is restricted should not also try to define how email addresses and phone numbers are matched.
Why it matters: A focused scenario makes the behavior it specifies easier to see. - Unresolved matching questions: Describe how the pair handles email and phone matching details that they have not yet agreed with the team.
Why it matters: Recording an open question lets the team keep formulating without treating an assumption as an agreed rule. - Similar examples as an outline: Describe why Tracey suggests a scenario outline after the team considers the case where neither contact detail matches.
Why it matters: Recognizing similar examples can help the team present variations of the same behavior together.
Key terms: rule, scenario, restricted, blocklist, matching rules, question cards, requirement workshop, exact, character-for-character matching, scenario outline, example map
9.11 Formulation gets faster
The section shows how consistent, readable phrasing makes later scenarios quicker to formulate, while warning against sacrificing clarity for step reuse.
- Consistent scenario phrasing: Explain why the first scenarios take longer to formulate and how later, similar scenarios become quicker.
Why it matters: A consistent way of expressing behavior saves effort as the team formulates more examples. - Readability before step reuse: Justify why a team should favor consistent, readable scenario steps over making steps maximally reusable.
Why it matters: Step reuse saves work only when the resulting scenario still communicates the behavior clearly. - Authentication independent restriction examples: Describe what the two restriction examples establish and why another scenario need not specify authentication status.
Why it matters: A focused example can establish a distinction without repeating it throughout the specification.
Key terms: formulating, ubiquitous language, steps, step reusability, readability, consistency, action-like steps, Restrictions are independent of authentication status, restricted customer, contact details
9.12 Incremental specification
The section explains how high-level scenarios can guide functionality delivered in small increments, and why similarly small steps help control risks when using AI to generate code.
- Low to high fidelity delivery: Explain how small increments can begin with a low-fidelity implementation and build toward functionality suitable for release, while allowing the team to get feedback before all the work is done.
Why it matters: An early increment can be useful for feedback without being mistaken for the finished feature. - Intent-focused evolving scenarios: Describe why a high-level scenario can state the intended behavior without fixing technical details, and how that scenario can remain useful as implementation and automation change.
Why it matters: Keeping the intended behavior separate from technical choices lets the specification survive implementation changes. - Small steps for AI work: Explain why large AI coding tasks pose risks and how small, controlled steps and version-controlled scenarios can reduce those risks without guaranteeing success.
Why it matters: Small steps make it easier to keep AI-generated work aligned with the intended requirements, though oversight remains necessary.
Key terms: small increments, low fidelity, high fidelity, high level scenario, implementation details, rules and scenarios, automation code, context window, small, controlled steps, scenarios
9.13 Documenting with a tag
This section explains how Gherkin tags document information outside a scenario’s expected behavior, using @manual to mark a scenario the team has chosen not to automate.
- Purpose of Gherkin tags: Explain what a Gherkin tag documents, why it should be business-readable, and how it can affect scenario automation.
Why it matters: Tags let the team communicate specification details without making the behavior steps less clear. - Tag syntax and placement: Describe where tags can be placed and the basic rules for writing them.
Why it matters: Correct syntax and placement make a tag usable and prevent differently spelled tags from being confused. - Inherited tags across blocks: Trace which scenarios receive tags applied to a feature, rule, or examples block.
Why it matters: A tag’s placement determines which scenarios receive it without repeating the label on each one. - Manual scenario trade-off: Explain why the team marks a scenario @manual and what risk comes with leaving scenarios unautomated.
Why it matters: Marking a scenario as manual makes its status visible without mistaking the tag for protection against outdated documentation.
Key terms: Gherkin tag, feature file, step text, feature, rule, scenario, scenario outline, examples block, case sensitive, implicitly applied
9.14 Who does what and when
This section explains when formulated scenarios should be reviewed and who should review them before the team relies on them.
- Timing of scenario review: Explain why scenarios should ideally be reviewed as soon as they are formulated, before automation or production code begins, while recognizing that some teams start implementation before review is complete.
Why it matters: Reviewing early can catch a mistaken specification before the team builds from it. - Team review and product accountability: Describe why the whole team should review formulated scenarios, especially the first ones in a new functional area, and state the PO’s minimum review responsibility.
Why it matters: Shared review helps make the scenarios a specification the team and product owner can stand behind.
Key terms: scenarios, review, automation, production code, formulation, example mapping, business readable terminology, PO, product specification
9.15 Summary
Where this is used later
- Step definitions (chapter 12) · The discussion of step definitions can build on the distinction between scenario text and generated snippets.
- Personas (chapter 17) · Provides the reason for making actors explicit when discussing personas.
- What about “they”? (chapter 13) · Revisits how scenarios refer to an actor with “they”.
- In-place Persona pattern: persona definitions in feature files (chapter 17) · The section identifies the In-place Persona pattern as a situation where a Background may be useful.
- Tagging scenarios with automation details (chapter 10) · The distinction between stated scenario context and context left implicit.
- Ensure pattern: managing implicit dependencies (chapter 16) · Setting the context in formulated scenarios
- Evolving with fast feedback (chapter 12) · Incremental specification through small steps.
- Documentation evolves (chapter 10) · Provides a basis for considering how documentation evolves as functionality is refined.
Concepts explained in this chapter
- readabilityThe ease with which written scenario text can be read and understood.
- formulationThe behavior-driven development practice of expressing understood behavior as precise scenarios.
- scenarioA business-readable description of an example system behavior and its expected outcome.
- scenario reviewA collaborative examination of behavior scenarios to identify ambiguity, omissions, or errors and establish agreement before implementation.
- background blockA Gherkin section whose steps establish context shared by scenarios in a feature file.
- tagAn @-prefixed metadata label that annotates and categorizes Gherkin elements.
- exampleA concrete instance illustrating an expected behavior or a possible outcome of a rule.
- specificationA sufficiently complete description of a solution's required behavior and characteristics for a delivery team to design and implement it.
- shared understandingA common interpretation of requirements and expected behavior held by the members of a team.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
