## Definition **Refining specifications** is the process of transforming raw collaborative examples into polished, self-explanatory, focused executable specifications. In [[Specification by Example - Gojko Adzic]], raw examples from a workshop are uncut diamonds — they capture the right material but are not yet fit for use as long-lived documentation or as an unambiguous development target. ## Scripts versus specifications The most important refining move is converting scripts into specifications. A *script* describes how something can be tested: it narrates workflow steps, names UI controls, references session state, and buries the business rule inside a sequence of actions. A *specification* describes what the system must do: it declares a context, a single triggering action, and the expected outcome, without prescribing implementation. ``` Script (avoid): 1. Log in as Tom. 2. Navigate to home page. 3. Search for "Specification by Example." 4. Add first result to cart. 5. Verify item count is 1. Specification (prefer): Given a registered user with an empty shopping cart, When the user adds one book to the cart, Then the cart contains exactly one item. ``` Scripts decay quickly: any UI restructuring breaks them even when the underlying rule is unchanged. Specifications are stable because they say nothing about the implementation. ## Pushing technical concerns into the automation layer Executable specifications have two layers: the *specification layer* (human-readable, business vocabulary) and the *automation layer* (code that binds the spec to the system). Technical difficulties — legacy quirks, asynchronous coordination, database identifiers — belong in the automation layer, not in the spec. When teams include workarounds in the spec itself, every design improvement to the system also requires the spec to be updated. The automation layer absorbs change; the specification remains stable. ## The self-explanatory test A specification is self-explanatory when someone who was not in the original workshop can read it and state the business rule it represents. Adzic's practical test: show the specification silently to a colleague and ask them to explain it. If you find yourself talking, write down what you said and put it in the specification header. A descriptive title and a one-paragraph explanation of the example structure — written *after* the examples exist — dramatically reduce the time spent on future regression diagnosis. ## Evolving a specification language As specifications accumulate, successful teams converge on a shared specification language: a set of reusable step phrases and domain terms that reduce duplication in the automation layer and keep specifications consistent. Teams that allow each story to introduce its own vocabulary end up with "57 ways to navigate to a page." Maintaining the language means periodically refactoring steps to match evolving domain concepts — the same ubiquitous language principle as in domain-driven design. ## Focus and single-action rule A specification should trigger *one* action. Multiple actions in a single spec obscure which action caused a failure and require readers to mentally trace the interaction to understand the intent. If a group of actions is important enough to appear together repeatedly, it deserves a named domain concept in the automation layer — not inline repetition in the spec. ## Related - [[Specification by Example]] - [[Gherkin Scenario]] - [[Key Examples]] - [[Living Documentation]] - [[Executable Acceptance Criterion]] ## Sources - [[Specification by Example - Gojko Adzic]]