Book-Reader-Assist/library/Spec Driven Development/Chapter-05-Anatomy-of-a-specification/Chapter-05-chapter-notes.md

Spec Driven Development — Chapter 05: 2 - Anatomy of a specification

• Date Created: 2026-10-01
• Status: Complete
• Reading Span: PDF pages 33–42

---

1. Pre-Reading Briefing

• Core Question: What information must a specification contain so someone can build and check the intended behavior without filling gaps by guesswork?
• Key Points to Watch For:
  • Notice where Ködel draws the boundary between what belongs in a specification and what belongs in a later implementation plan.
  • Track how he moves from a vague to-do app idea to a defined problem, intended user, and scope.
  • Distinguish scenarios, rules, and acceptance criteria. Ask what each contributes to checking the result.
  • Look for the less obvious cases and assumptions that could change the solution if left unstated.
  • Observe how he handles ambiguity and whether the reference to FOCUS Architecture gives enough context to continue without that volume.
• Context & Thread from Prior Chapters: Chapter 4 treated the specification as a living target and the reader identified testing against it as essential after an AI-assisted rewrite. This chapter examines what must be written in that target for the check to be meaningful. Keep the earlier distinction between the intended behavior and the technical plan in view.

---

2. Reading Review & Reflections

• Prompt Questions:
  1. In the to-do app example, what belongs in the specification and what belongs in the later plan? Give one example of each, and explain why the distinction matters.
  2. How do a scenario, a rule, and an acceptance criterion do different jobs? Use one to-do app behavior to explain them in your own words.
  3. If a requirement leaves room for two interpretations, what should happen before coding? Name one edge case or assumption you would make explicit in the spec.
• User Key Takeaways:
  1. “Requirments, Scope, Non-goals, behaviour,edges belong in the spec. How do do it and what tech to use comes later”
  2. “sCENARIO IS A user story (as a user When I do this .. this needs to happen) , rules in the book tell us what the spec has in it, acceptance criterion are testable and measurable things the app needs to do in order to quantify if the development is done”
  3. “edge-case for a user data - what happens when someone changes their name , assumption would be that they way people write dates is the same”
• Scaffolding & Feedback: The reader correctly separated behavioral requirements and scope from technology and implementation decisions, and recognized scenarios as user-facing stories and acceptance criteria as checks for done and correct. Add the problem and intent (the why) to the spec. In Ködel's terms, a rule is a constraint on behavior that must always hold, such as forbidding task text made only of spaces; it is not the list of sections in a spec. A changed name can be an edge case for an app with profiles, but it is outside this chapter's single-user to-do app. A shared date-writing convention is a fragile assumption; if dates matter, the accepted format or interpretation should be made explicit. The reader did not yet address what to do when a requirement has two plausible meanings: the AI or developer should ask and record the decision in the spec before coding. Follow-up prompt: For a to-do app, write one rule and one acceptance criterion for creating a task with blank or spaces-only text. If “blank” is unclear, what should happen before code is written?
• Follow-Up Response:
  • Rule: “A to-do task must contain at least one non-whitespace character after leading and trailing spaces are trimmed.”
  • Acceptance criterion: “If the task text is empty or contains only spaces, the task is not saved and the user sees a validation message; if it contains any non-space character, it can be saved.”
• Follow-Up Feedback: The reader now distinguishes a general constraint from observable pass/fail behavior. One wording gap remains: “non-whitespace” in the rule includes rejecting tabs and line breaks alone, while “non-space” in the criterion could allow them. Align the criterion with the rule: reject text containing only whitespace, and allow saving when at least one non-whitespace character remains. If “blank” has more than one plausible meaning, ask and record the answer before coding. This is the kind of ambiguity the chapter asks a spec to surface.
• Clarified Acceptance Criterion: If the task text is empty or contains only whitespace (including spaces, tabs, or line breaks), saving is blocked and the user sees a validation message. If it contains at least one non-whitespace character after trimming, it passes task-text validation.

---

3. Chapter Synthesis

• Core Thesis: Ködel argues that a useful specification turns a vague intention into clear, testable statements of purpose, scope, behavior, and edge conditions while leaving technical implementation choices for the plan.
• Key Concepts / Mental Models:
  • What and why versus how: State the user's problem and intended behavior in the spec; choose technologies and internal design in the plan. Use this boundary to keep behavior checkable even if the implementation changes.
  • Scope: in, out, non-goals: Identify what this version includes, what might come later, and what the product is deliberately not trying to be. Use these boundaries to prevent unrequested work.
  • Scenario, rule, acceptance criterion: A scenario describes a user's interaction; a rule is a constraint that must always hold; an acceptance criterion states an observable condition for deciding whether the behavior is correct. Write all three for important behavior.
  • Edges and assumptions: Name unusual or invalid inputs, assumptions that could change, and external dependencies. Confirm uncertain assumptions before building on them.
  • Clarity for people and AI: Wording should support one reasonable interpretation and a practical check. When ambiguity remains, ask and record the decision in the spec.
• Notable Arguments & Evidence: Ködel develops a to-do app example from a loose idea into problem, scope, behavior, criteria, and edges. He contrasts vague claims such as “fast” with a measurable check involving a list of 100 tasks. These examples explain how to find gaps; the chapter does not measure whether using this structure improves outcomes across projects.
• Updates to Prior Understanding: Chapter 4 called the specification a living target for short cycles. Chapter 5 gives that target a structure and shows why the reader's Chapter 4 check—testing revised code against the spec—depends on precise rules and criteria. It also keeps Chapter 3's what/why separate from later decisions about where code belongs.
• Weekly Action Item: Turn the reader's task-text rule into a mini-spec and check three inputs against it: empty text, whitespace-only text including tabs, and text containing a visible character. Record the expected save behavior and validation message for each.