Writing Great Specifications

Nicieja opens with a confession that reverberates throughout the entire book: “As programmers, we’re taught to write code—algorithms, design patterns, abstractions. But when we get our entry-level jobs, our employers expect us to ‘deliver value to our clients.’” The author illustrates this with a banking example—knowing how to code is not the same as knowing how to translate banking into code. This gap, between technical fluency and domain understanding, is the foundational problem that executable specifications exist to solve. The implication is profound: the primary bottleneck in software delivery is not technical incompetence but communicative failure. An IBM and Bell Labs study showed that 80% of all product defects are inserted at the requirements-definition stage. The bridge between business and technology, Nicieja argues, “can only be built with empathy—understanding other people’s problems—and inclusive communication.” This reframes the software engineer’s role from code-producer to translator, and it makes the quality of that translation—the specification—the single highest-leverage artifact in the development process.

#1 The Bridge Builder’s Burden: Software as Translation Between Worlds [Principle]

Ref. FA04-A

“The one and only reason teams need specifications is information asymmetry,” Nicieja writes with unusual directness. “Teams need to distribute information evenly among the stakeholders to create the best possible product.” This insight strips away the bureaucratic connotations of the word “specification” and reveals its true function: a mechanism for equalizing knowledge. When one party—be it a product owner, a designer, or an engineer—possesses information that others lack, the product suffers from blind spots. Specifications serve two corrective functions: they define acceptance criteria that let teams know when they’ve succeeded, and they cultivate a common language that enables mutual understanding. The deeper lesson is that specifications are not documents for documents’ sake; they are instruments of epistemic equity, and any specification practice that fails to reduce information asymmetry is failing at its only job.

#2 The Asymmetry Trap: Why Teams Need Specifications at All [Principle]

Ref. 6AB8-B

Nicieja identifies five anti-patterns that plague specification efforts: over-specification, hand-offs, under-documentation, speci-fiction, and test-inability. Each sin represents a different failure mode in the communication between business and technology. Over-specification paralyzes teams with analysis paralysis. Hand-offs fragment the flow of understanding by separating those who analyze requirements from those who implement them. Under-documentation, the backlash against over-specification, leaves teams with no institutional memory. Speci-fiction—the author’s playful coinage—describes specifications that “pose as a single source of truth but can’t be one because nobody cares to update them.” And test-inability is the failure to bake testability into requirements from the outset. The taxonomy is valuable because it reveals that the space between too much specification and too little is narrow, and that the solution is not a matter of quantity but of kind—living, executable, conversation-based specifications that evolve with the product.

#3 The Five Sins of Specification: A Taxonomy of How Teams Fail [Pattern]

Ref. B035-C

At the heart of specification by example lies a deceptively simple idea: conversations between domain experts and the delivery team are the foundation of the entire development process. Nicieja organizes SBE’s seven key patterns into three groups revolving around conversations: having them, capturing them, and automating them. “Patterns focused on having conversations aim to increase the knowledge flow between the delivery team and the business,” he writes, “without sacrificing agility.” This is a radical reorientation from the traditional view of specifications as documents to be authored and delivered. Instead, specifications become the residue of structured dialogue—artifacts that preserve the understanding generated when people with different expertise talk to each other. The implication is that the quality of your specification is bounded by the quality of your conversations, and that investing in better conversations yields better specifications more reliably than investing in better writing alone.

#4 The Conversation at the Center: SBE’s Radical Reorientation [Principle]

Ref. B9AA-D

“Humans prefer stories illustrated with examples,” Nicieja observes, and then demonstrates why with a devastating comparison. An abstract requirement—“The writers should split the salary based on their contribution”—leaves the concept of “contribution” open to interpretation. But a concrete example—“John and Gilly wrote 100 pages each, so they should get 40% of the salary”—eliminates ambiguity in a split second. Examples, Nicieja argues, are “anchors, links, cognitive shortcuts” that “reduce the likelihood of misunderstanding the purpose of a story.” The deeper principle is epistemological: abstraction, while powerful for generalization, is dangerous at the requirements stage because it conceals the very ambiguities that will later become bugs. Concrete examples force participants to confront their assumptions and discover misalignments before a single line of code is written. This is why SBE insists on illustrating every requirement with specific, testable examples rather than leaving them at the level of abstract statements.

#5 The Concreteness Imperative: Why Examples Defeat Abstractions [Wisdom]

Ref. 8C5D-E

“Only working production code holds the truth about the system,” Nicieja acknowledges. “Most specifications become outdated before the project is delivered.” This is the problem of speci-fiction writ large: documentation decays because no force compels it to stay current. The solution is automation—linking specifications directly to testing code so that when the system changes, broken specifications signal that the documentation is out of date. “When tests keep specifications in check, they let specifications with examples evolve into a documentation system.” This creates what Nicieja calls living documentation: “documentation that changes along with the system it documents, thanks to the link between the text and the code as well as frequent validation.” The insight here is that the only sustainable documentation is documentation that is continuously verified against reality—and that executable specifications are uniquely positioned to achieve this because they are simultaneously human-readable requirements and machine-executable tests.

#6 The Living Document: How Automation Defeats Entropy [Strategy]

Ref. 099B-F

Every executable specification, Nicieja explains, comprises two complementary layers: a specification layer and an automation layer. “Without the specification layer, an executable specification wouldn’t be a specification. Without the automation layer, it wouldn’t be executable.” The specification layer contains human-readable Gherkin documents that store acceptance criteria, convey them as scenarios, and cultivate the ubiquitous language. The automation layer executes a simulation of the application to verify that the code behaves as the specification dictates. This architectural insight is crucial because it establishes that the two layers serve different audiences and must be optimized for different concerns. The specification layer must be readable by non-technical stakeholders; the automation layer must be technically rigorous. When teams conflate the two—writing specifications that look like SQL tables or testing code—they compromise both readability and testability.

#7 The Two Layers: Architecture of an Executable Specification [Principle]

Ref. D52C-G

“I strongly advocate taking the perspective of a specific group of stakeholders: the end users,” Nicieja writes in his discussion of outside-in development. The author contrasts a system-oriented scenario—“When the content is analyzed / Then the sentence that is too long should be detected”—with a user-oriented version: “When Vladimir writes a sentence that is too long / Then he should be notified that the sentence could be shortened.” The shift is subtle but transformative. By centering the user, the scenario invites questions about the user’s experience: Would this notification distract Vladimir while writing? Should there be a separate editing mode? Outside-in development, Nicieja argues, “forces you to think about the people who define software requirements and try to understand why they want what they want.” The deeper implication is that technical language in specifications is not neutral—it actively obscures the user’s perspective and reduces the team’s capacity for empathy-driven design.

#8 The Outside-In Imperative: Writing Scenarios for Humans, Not Systems [Strategy]

Ref. F381-H

In a revealing passage about naming actors in scenarios, Nicieja shares how he “called the user in most of my scenarios Simona. Every time I wrote a scenario, I imagined that she was anxious to get her work done as quickly as she could, because she had a sick child at home.” This practice, borrowed from user-centered design, transforms abstract “users” into specific people with motivations, constraints, and emotional states. The specification becomes not just a technical document but a vehicle for empathy. Nicieja argues that “real names and user-oriented scenarios facilitate empathy” and that using concrete names like Mike or Vladimir—rather than “team member 1” and “team member 2”—makes scenarios more readable and more emotionally resonant. The insight extends beyond naming: it suggests that the quality of a specification is partly determined by the richness of the human models it embeds, because richer models lead to more thoughtful design decisions.

#9 The Persona as Empathy Engine: Why Mike Matters More Than “User” [Strategy]

Ref. 2073-I

“Don’t write scenarios about the UI,” Nicieja advises. “Write about business outcomes. Nobody cares about the UI; they care if they can get their job done.” He contrasts an imperative, interface-oriented scenario—‘Given “Export” button from the “File” menu was clicked’—with a declarative, outcome-oriented version: “When Vladimir saves ‘Lolita’ as a PDF / Then a formatted PDF should appear where Vladimir saved it.” The imperative style, he argues, couples specifications to implementation details that change frequently, eroding trust in the specification suite. The declarative style describes what the user achieves without prescribing how the interface should look. Citing Liz Keogh, Nicieja notes that “every declarative is a chunking-up of something else, and every imperative is a chunking-down.” The practical wisdom here is that specifications should be written at the level of business intentions, not UI mechanics, because intentions are stable while interfaces are volatile.

#10 The Declarative Discipline: Intentions Over Interfaces [Strategy]

Ref. CC98-J

“The easiest way to start writing a Gherkin scenario is to begin with the end in mind—the Then,” Nicieja counsels, drawing a parallel to how “most good writers never start writing without figuring out the ending.” This compositional technique is not merely a writing trick; it embodies a fundamental business insight. Nicieja invokes marketing theory: “Nobody wants to buy a drill for the sake of buying a drill. Sometimes, though, people need a hole in a wall.” Customers, he argues, “want to buy a specific outcome your product will produce. And Thens are the outcomes.” By starting with Thens, specification writers force themselves to articulate the value the system must deliver before concerning themselves with the mechanism of delivery. This aligns specification writing with the Jobs-to-be-Done framework and transforms the Given-When-Then template from a testing notation into a tool for outcome-driven product design.

#11 Begin with the End: The Power of Starting with Thens [Strategy]

Ref. D109-K

“Ideally, a scenario should be three sentences long and feature one Given, one When, and one Then,” Nicieja writes. “Just as short stories focus on only one theme, each scenario should be composed to talk about only one acceptance criterion.” The one-When rule is not arbitrary—it prevents the coupling of unrelated business rules within a single scenario, which makes failures ambiguous and analysis difficult. When a scenario has two Whens, “you can never be sure which When caused the outcome to happen.” Nicieja distinguishes between user tasks—high-level instructions that describe a single business activity—and user actions, which are lower-level steps that clarify a task. Multiple user actions within a single When are acceptable; multiple user tasks are not. The literary metaphor is apt: trying to fit the complexity of a novel into the form of a short story yields confusion, not clarity.

#12 The One-When Rule: Scenarios as Short Stories, Not Novels [Pattern]

Ref. 65E9-L

“Givens have a role in scenarios that’s similar to world-building in storytelling,” Nicieja writes, drawing an analogy to Tolkien’s One Ring. “A Given creates a snapshot of the represented world and its history before the action of the scenario can take place. The snapshot stays static until the actors change it with their actions.” The practical corollary is that Givens should be written in passive voice and past tense—as lists of preconditions rather than active steps. This distinction matters because Givens written as actions (e.g., “Given Vladimir writes a sentence”) create hidden dependencies on other steps, making scenarios fragile and difficult to reuse. Passive Givens (e.g., “Given text:”) are modular building blocks that can be rearranged freely across scenarios. The insight reveals that the Given-When-Then template is not merely a syntactic convention but a semantic architecture: context, action, and consequence, each with its own grammatical and compositional rules.

#13 Givens as World-Building: The Art of Static Snapshots [Pattern]

Ref. 83D5-M

When faced with a blank page, Nicieja recommends writing a “warm-up narrative”—a short, free-flowing story about a requirement in action, written before any Gherkin. “Sketch out a few moments of a day in the life of one of the actors,” he advises. “When writing, don’t think about implementation yet. Ignore any technical limitations of your current system.” He illustrates with a narrative about writers struggling with blank pages—a meta-moment where the technique addresses the very problem it solves. The warm-up narrative serves as a bridge between unstructured conversation and structured specification, giving teams permission to explore requirements through storytelling before committing to the rigidity of Given-When-Then. The deeper principle is that creativity and precision are sequential, not simultaneous: you must first understand the human situation broadly before you can specify it precisely.

#14 The Warm-Up Narrative: Writing Before You Write [Strategy]

Ref. 1A4E-N

Nicieja introduces two powerful heuristics for discovering missing scenarios: context questioning (“Is there a context that, for the same event, produces a different outcome?”) and outcome questioning (“Is there another outcome that also matters?”). Applied to a simple scenario about revising drafts, context questioning reveals the edge case of cloud synchronization conflicts—a context where the usual replacement behavior would be destructive. Outcome questioning, applied to a cloud storage upgrade scenario, reveals the forgotten business rule of charging the user’s credit card. These techniques combat the “sense of closure” that descends after writing a scenario—the false belief that a single scenario captures the full requirement. They transform specification writing from a one-shot exercise into an iterative exploration, where each scenario generates questions that lead to more scenarios, progressively tightening the mesh of the specification.

#15 Context and Outcome Questioning: Mining Scenarios for Hidden Edges [Strategy]

Ref. 571F-O

Nicieja opens Chapter 5 with a startling analogy: for decades, car crash tests used only male-sized dummies, causing female passengers to face 20-40% higher risk of death or serious injury. “Even the most basic placeholders can influence the results of a test in a dramatic and horrific way,” he writes. In Gherkin, the equivalent danger is using fake or generic data in scenarios. Fictional examples—sentences manufactured to pass validation rather than drawn from the real world—“poison your decision making” because they prevent teams from discovering domain-specific quirks that real data would reveal. The role of data in Gherkin, Nicieja argues, “is to inform decisions and ensure continuity of research and discovery in the software development process.” Authentic examples drawn from the business domain serve as anchors to reality, ensuring that specifications reflect the world as it is rather than as the team imagines it to be.

#16 The Crash Test Dummy Problem: Why Fake Data Poisons Decisions [Wisdom]

Ref. DA99-P

Nicieja draws a distinction that reshapes how teams should approach testing: illustrative examples versus exhaustive examples. “An exhaustive list of examples is like a list of all the contacts on your phone,” he writes. “Illustrative examples, on the other hand, contain one key example from each of your important social circles.” The distinction matters because executable specifications serve a dual purpose—testing and communication—and exhaustive examples optimize for the former at the expense of the latter. A specification cluttered with hundreds of test cases becomes unreadable, defeating the purpose of living documentation. The guiding principle is to include “each important aspect of business functionality,” “each important technical edge case,” and “each particularly troublesome area of the expected implementation”—no more, no less. This is not a compromise on quality but a recognition that in specification by example, clarity is itself a form of quality.

#17 Illustrative Over Exhaustive: The Art of Choosing Key Examples [Principle]

Ref. 909E-Q

Beyond the happy path, Nicieja catalogs a vivid taxonomy of failure scenarios: the angry path (what breaks the system), the scary path (what could get someone fired), the embarrassing path (what would humiliate the CEO during a demo), the delinquent path (security and compliance failures), the stressful path (scale and performance limits), the greedy path (power users who maximize everything), the forgetful path (memory exhaustion and abandoned processes), the desolate path (empty states and missing inputs), and the indecisive path (users who constantly change their minds). This taxonomy transforms scenario generation from an ad hoc brainstorming exercise into a systematic exploration guided by a checklist. Drawing on Atul Gawande’s The Checklist Manifesto, Nicieja argues that “under pressure, people tend to skip some steps. A checklist with possible testing ideas, ingrained in your development process, can help you avoid that.” The insight is that comprehensive specification requires not just creativity but structured imagination.

#18 The Exploratory Paths: A Taxonomy of Unhappy Outcomes [Pattern]

Ref. A53B-R

“Boomerangs are functionalities that keep breaking every now and then, returning from production to development despite your team’s best efforts,” Nicieja explains. They signal deeper problems: complex domain rules that outsiders struggle with, unidentified stakeholders, bus-factor-of-one knowledge silos, or customer dissatisfaction with technically correct solutions. Executable specifications help by converting each recurrence into a regression example that prevents future breakage. “The more often they return, the more prominence they deserve—more tests and more examples, which then become documentation.” Nicieja connects boomerangs to the Five Whys technique for root cause analysis, suggesting that each boomerang is an opportunity to deepen domain understanding. The specification suite becomes not just a test suite but an institutional memory that captures and preserves the hard-won lessons of production failures.

#19 Boomerangs: The Specifications That Come Back to Haunt You [Pattern]

Ref. 5A70-S

Nicieja warns against a seductive anti-pattern: writing Gherkin tables that mirror database schemas. He shows a horrifying example where a Background section includes relational tables with publisher_id, item_id, and author_id columns—technical artifacts that have nothing to do with the business rule being specified. “Writing outlines that look like SQL tables is an anti-pattern,” he declares. “You should always solve technical difficulties in the automation layer, instead of trying to solve them in the specification layer.” The cleaned-up version replaces foreign keys with natural language: “Given Dominic bought ‘Writing Great Specifications’.” The principle is that Gherkin is “a business-readable, domain-specific language” and “there’s nothing business-y, readable, or domain-specific about database rows.” Teams who use the specification layer as a shortcut for manipulating test data sacrifice the entire communicative purpose of executable specifications for marginal automation convenience.

#20 The Anti-SQL Principle: Keeping the Specification Layer Business-Readable [Pattern]

Ref. 4F61-T

When specifications use classes of equivalence—abstract ranges like “less than 18 years old”—Nicieja argues they create “an illusion of shared understanding.” Mental operations on sets don’t come naturally to most people, and when those sets are expressed in domain-specific terms, the cognitive burden doubles. His remedy is the Goldilocks principle, borrowed from the children’s story: always provide at least three examples—one below the boundary, one at the boundary, and one above it. Instead of “Given a user who is less than 18 years old,” write a scenario outline with ages 17, 18, and 19, each producing a clear outcome. “Wherever you find yourself trying to express an example as a class of equivalence, rewrite it using the Goldilocks principle with concrete examples of the boundaries,” Nicieja advises. The principle converts abstract mathematical conditions into concrete stories that any reader can verify at a glance, embodying the book’s central commitment to concreteness over abstraction.

#21 The Goldilocks Principle: Three Bears of Boundary Testing [Strategy]

Ref. B65D-U

Through the story of Peter—a new team member from Poland confused by undefined domain terms in a specification—Nicieja demonstrates how living documentation self-corrects through human feedback loops. Peter notices that “screening” and “qualifying” are used interchangeably, that “tenant leads” and “candidates” seem synonymous, and that nowhere does the specification explain what a “tenants pipeline” is. The fix involves adding definitions to the specification brief, enforcing consistent terminology, and documenting the business context of the screening process. “There’s nothing wrong with the fact that the changes are only happening now, after Peter pointed them out,” Nicieja writes. “That’s why we talk about a living documentation system. Such a system employs feedback loops to correct itself over time.” The insight is that living documentation is not about getting everything right the first time—it is about creating a system where imperfections are continuously discovered and repaired, whether through automated test failures or human encounters with confusion.

#22 The Living Documentation Feedback Loop: Peter’s Problem [Revelation]

Ref. FF31-V

As specification suites grow, the generic Feature keyword becomes a catch-all that accommodates loosely related scenarios until specifications become unwieldy. Nicieja shows how a single “Creating events” feature grew to 75 lines covering four distinct areas of implementation. The solution is to refactor features into abilities—specifications named from the stakeholder’s perspective: “HR reps can organize their wellness programs through online events” or “Team leads can facilitate teamwork by organizing team outings online.” The Ability keyword forces writers to articulate who benefits and what they can achieve, creating a specification suite organized as “a map of clients and the value the company delivers.” This refactoring is not cosmetic—it changes how teams think about requirements by anchoring each specification to a specific stakeholder and outcome, making the suite navigable and preventing the feature-bloat that turns living documentation into an unreadable sprawl.

#23 From Features to Abilities: Refactoring the Specification Suite [Strategy]

Ref. 4D31-W

Nicieja introduces the Business Need keyword for specifying functional aspects of nonfunctional requirements like security and performance. But the deeper insight emerges through narrative: when Activitee’s sales team presents security scenarios to a prospective client, a previously unknown stakeholder—the Chief Information Security Officer—becomes personally involved, demanding SSO support that the team hadn’t anticipated. “New business needs usually imply that there’s a stakeholder the team hasn’t yet explicitly identified,” Nicieja writes. Business needs act as early warning systems, signaling that someone with authority is working behind the scenes, influencing requirements without being directly engaged. The implication for specification practice is strategic: when a new nonfunctional requirement appears “seemingly out of nowhere,” the team should investigate not just the technical solution but the stakeholder who generated the demand, because engaging that stakeholder directly would have prevented the scope surprise.

#24 Business Needs as Stakeholder Detectors: The Hidden CISO [Revelation]

Ref. 36A5-X

In the book’s culminating architectural vision, Nicieja draws on domain-driven design to organize specification suites according to the structure of the business itself. As suites grow beyond what a simple split between abilities and business needs can handle, teams must distill business domains from their ubiquitous language—identifying core domains, secondary domains, and generic domains. The specification suite becomes a map that mirrors the organization’s domain model, with bounded contexts preventing terminology collisions between teams. “A ubiquitous language must grow out of blending technological expertise with business expertise in reasonable proportions,” Nicieja writes. A specification suite organized by domain serves multiple purposes simultaneously: it documents the business for newcomers, preserves the team’s decision-making history, and provides a navigable structure for finding relevant scenarios. The ultimate aspiration is that the specification suite becomes isomorphic with the business itself—a mirror that reflects not just what the software does, but why it exists and whom it serves.

#25 The Domain-Driven Suite: Specifications as Maps of Business Reality [Wisdom]

Ref. B5D0-Y