Watch
Introducing Example Mapping
Demonstrates breaking a story into rules, concrete examples and open questions on colored cards, which surfaces missing edge cases before anyone writes code.
Requirements and Acceptance Criteria
Mistakes to catch in review
An export feature marked done that silently omits archived records, because no criterion said whether to include them.
'Fast search' implemented as a prefix match that was only ever tried on 100 test rows, because the requirement gave no latency target or data size.
A double-clicked submit button that creates two orders, because nobody specified what happens on a duplicate submission.
Turning intent into specific, checkable statements of what the software must do and how well, so done has a definition before work starts.
Topics
- Functional and Quality Requirements
- Separating what the system does from how well it must do it, with latency, availability, cost, accessibility and security stated as explicit targets.
- Testable Acceptance Criteria
- Criteria that are binary and observable, so a test, a reviewer or an agent can say pass or fail without interpretation.
- Specification by Example
- Using concrete inputs and expected outputs, including Given/When/Then scenarios, to pin down behavior that prose leaves ambiguous.
- Edge Cases and Error Behavior
- Deciding in advance what happens with empty, duplicate, oversized, malformed and simultaneous inputs.
- Hunting Ambiguity
- Reading a requirement the way a literal-minded agent would, and fixing every word that could mean two things.
You understand it when you can
- Write acceptance criteria for a feature where every criterion can be checked by a test or a single observation.
- Rewrite a vague requirement such as 'the page should load fast' into a measurable one with a threshold and a way to measure it.
- List the edge cases for a form or API endpoint and state the expected behavior for each.
Drill
An agent wrote five acceptance criteria for a password reset feature, including 'the reset flow should be secure and fast' and 'users get a reset email'. Find every criterion that cannot be checked by a test or a single observation, and rewrite each one with a threshold, an example or an explicit edge case.
Start here
Watch
Essential Software Requirements - Karl Wiegers
Wiegers walks through the core practices from his 2023 book, including separating functional from quality requirements and making each requirement verifiable.
Beauty in Code 2019, 6 of 6 — Dan North: "BDD Is Not About Testing"
The originator of BDD explains Given/When/Then as a way to reach shared understanding of behavior, not as test syntax, which is the point of specification by example.
Read
Software Requirements Essentials: Core Practices for Successful Business Analysis
Twenty short, practical chapters on eliciting, specifying and validating requirements, including quality attributes with measurable targets and acceptance criteria.
Specification by Example: How Successful Teams Deliver the Right Software
Case studies from dozens of teams showing how key examples become executable acceptance criteria that remove ambiguity from prose requirements.
Software Requirements
The standard reference on requirements, with detailed chapters on nonfunctional requirements, writing unambiguous requirements and reviewing them for testability.
Primary sources
Reference
Gherkin Reference (Cucumber documentation)
The authoritative syntax for Feature, Rule, Scenario, Given/When/Then and Examples tables, the format agents and test runners read for executable acceptance criteria.
Reference
EARS: The Easy Approach to Requirements Syntax
Alistair Mavin's five sentence templates (ubiquitous, event-driven, state-driven, unwanted behavior, optional) for writing requirements that cannot be read two ways.