A specification can become outdated as soon as the software changes. Living documentation addresses that problem by expressing expected behavior in business-readable scenarios and running those scenarios against the system. When a scenario fails, the team is alerted that the documented expectation and implementation do not agree; the failure does not, by itself, say which is wrong. section 6.4 section 1.3.4
Investigate a mismatch before changing either side:
- If the behavior is planned but not implemented, implement it when appropriate. section 6.4
- If the implementation is defective, fix the code and rerun the scenario. section 1.3.4
- If the expectation is outdated or contradictory, correct the scenario or resolve the contradiction. section 1.3.4
Creating it is collaborative work, not just test automation. Discovery produces examples; formulation turns them into readable scenarios; automation checks them. Keep the resulting rules and scenarios organized by coherent product functionality rather than by short-lived user stories, so readers can find what the system does after a story is delivered. section 1.7 section 10.1
Listing 10.1 Structure of the blocklisting feature file (scenario steps omitted for brevity)
Feature: Blocklisting Rule: Don't offer pay-on-collection for restricted customers # Two scenarios merged, because authentication is incidental Scenario: Restricted customer is not offered pay-on-collection option Rule: Customer's email OR phone must match those on blocklist Scenario Outline: Decide if customer is restricted Rule: Restrictions are independent of authentication status Scenario: Unauthenticated customer is restricted Scenario: Authenticated customer is restricted Rule: Blocklist is manually configurable @manual Scenario: Upload replacement blocklist
A blocklisting feature groups scenarios under business rules, such as whether a restricted customer is offered pay-on-collection. The grouping makes the documented behavior easier to navigate than a file for each delivery story. section 10.1
In a fixed-scope project, continuously validated scenarios can make decisions explicit where a static specification may already be stale. In a regulated project, versioned scenarios and execution reports can link expected behavior, checks, and results for a particular product version. Such reports still need preparation for formal requirements, and other documents may remain necessary. section 4.6 section 4.7



