Book-Reader-Assist/library/Spec Driven Development/Chapter-06-Requirement-Language-Writing-What-the-AI-Executes-Without/Chapter-06-chapter-notes.md

Spec Driven Development — Chapter 06: 2b - Requirement Language: Writing What the AI Executes Without Guessing

• Date Created: 2026-10-01
• Status: Complete
• Reading Span: PDF pages 43–56

---

1. Pre-Reading Briefing

• Core Question: How can a requirement sentence make its conditions, expected behavior, and check for correctness clear enough to guide a human or AI implementer?
• Key Points to Watch For:
  • Compare a complete specification structure with the precision of each sentence inside it; notice where ambiguity can remain.
  • Watch how Ködel separates functional requirements from technical construction decisions, building on Chapter 5's what/how boundary.
  • Identify the different questions answered by EARS, Given/When/Then, Design by Contract, and ATDD; look for where each fits in a spec.
  • Notice details that can disappear from a requirement: the starting state, the triggering condition, what must stay unchanged, and what must not happen.
  • Follow the edit-task example and ask which wording was open to two readings and how the team discovered that gap.
• Context & Thread from Prior Chapters: Chapter 5 gave the specification its parts: purpose, scope, behavior, criteria, and edges. Your task-text example showed how changing “non-whitespace” to “non-space” in one sentence alters what could pass. This chapter examines the language used inside those parts and how it affects implementation and checking.

Reading aid: four requirement approaches (PDF pages 52–53)

Notation	Answers	Where it goes in a spec	Sign that it is missing
EARS	Under what condition does the rule hold?	Functional requirements	A conditional requirement has no trigger and reads as though it always applies.
Given/When/Then	What concrete example demonstrates the rule?	Acceptance scenarios	A rule has no concrete example, or an example omits the initial state.
Design by Contract	What must hold before, after, and always?	Rules, edge cases, and assumptions	An invariant is unstated, allowing implementation to break it unnoticed.
ATDD	How do we know the feature is finished?	Success criteria and manual validation	A criterion is written after the code and fails to catch a defect.

The PDF clips the right edge of the final column. Those cells are paraphrased from the visible text and the surrounding explanation, not transcribed verbatim.

---

2. Reading Review & Reflections

• Prompt Questions:
  1. What makes a requirement functional rather than technical? Give one to-do app sentence of each kind and explain where each belongs.
  2. For rejecting a duplicate task title, how would an EARS-style rule differ from a Given/When/Then scenario? What does each force you to say explicitly?
  3. In the edit-task example, what ambiguity caused the failure? How could an invariant or an acceptance check written before coding have helped reveal it?
• User Key Takeaways:
  1. “functional describes observable behavior technical describes construction. tasks persist after app is closed is functional .. tasks get saved to a postgres database is functional.”
  2. “When the person creates a task with a filled-in, unique title, the system MUST register it and start showing it in the list. Given a task that already exists with a certain title, When the person tries to create another task with that same title, Then creation is refused with an error result explaining that the title already exists, and no new task is created.”
  3. “Invariant: the task's position in the list and its creation date do not change.”
• Scaffolding & Feedback: The reader correctly defined functional as observable behavior and technical as construction, and correctly identified persistence after reopening as functional. Saving to PostgreSQL is a technical plan choice; the final word “functional” in answer 1 should be “technical.” The Given/When/Then example includes the starting state, action, error, and absence of a new task. The EARS example is a valid event-driven requirement for creating a unique title, but it does not cover the duplicate case in the scenario. For the same duplicate case, an EARS rule would state its condition and required refusal, including no new task. The stated invariant about position and creation date is accurate, but the edit-task failure arose from an ambiguous duplicate-title comparison, not from breaking that invariant. Follow-up prompt: During an edit, should the task's own unchanged title count as a duplicate? What would happen when changing only its description if the implementation counted it?
• Follow-Up Response: “im not sure what would happen”
• Follow-Up Feedback: The task being edited should not count as another task with the same title. If the implementation checks against all tasks, it finds the task's own unchanged title and rejects an edit that changes only its description as a duplicate. Ködel's revised requirement specifies “among the other tasks.” A prewritten acceptance check for “edit only the description while keeping the title” would expose the wrong interpretation; the position and creation-date invariant is a separate guarantee.

---

3. Chapter Synthesis

• Core Thesis: Ködel argues that precise requirement sentences, concrete scenarios, explicit operation guarantees, and acceptance checks written before implementation reduce the room for a human or AI implementer to guess.
• Key Concepts / Mental Models:
  • Functional versus technical: Functional text states observable behavior; technical text chooses construction. Check whether a sentence still makes sense after changing the technology, then put it in the spec or plan accordingly.
  • EARS: Shape a rule so its trigger and obligation are explicit; use it to identify when a requirement applies and what the system must do.
  • Given/When/Then: State the initial situation, one action, and observable results, including the absence of unwanted side effects; use it as an example that tests the rule's meaning.
  • Design by Contract: State preconditions, postconditions, and invariants; use the invariant question to protect facts an operation must leave unchanged.
  • ATDD: Agree on feature-level acceptance checks before building; use them as a definition of done that is capable of failing the implementation.
• Notable Arguments & Evidence: The to-do app examples show how different forms reveal missing triggers, initial states, and guarantees. In the edit-task example, an ambiguous duplicate-title requirement allowed the agent to treat the task's own title as a duplicate; a prewritten description-only edit check failed and led to clearer wording. This is a concrete project example, not a measured comparison showing how often these approaches prevent defects.
• Updates to Prior Understanding: Chapter 5 supplied the specification's sections; Chapter 6 focuses on the precision of individual sentences inside them. The reader's earlier “non-space” versus “non-whitespace” gap is another case where nearly matching wording changes behavior.
• Weekly Action Item: For one small feature, write an EARS-style rule and a Given/When/Then check before implementation. Include one outcome that must not occur, then compare the finished behavior with both statements.