Book-Reader-Assist/library/Spec Driven Development/Chapter-07-The-Scope-of-a-Spec-How-Much-Fits-in-One-Specification/Chapter-07-chapter-notes.md

Spec Driven Development — Chapter 07: 2c - The Scope of a Spec: How Much Fits in One Specification

• Date Created: 2026-10-01
• Status: Complete
• Reading Span: PDF pages 57–63

---

1. Pre-Reading Briefing

• Core Question: How much work should one specification cover so it can be reviewed and its result checked as a useful piece of software?
• Key Points to Watch For:
  • Notice what Ködel treats as the unit of a spec, and how he tests whether the boundary is small enough to review but large enough to deliver value.
  • Compare his reasons for grouping “complete and reopen” while separating “create and delete.”
  • Watch how he proposes splitting a large feature and what becomes visible to a user after each slice.
  • Look for warning signs that a split follows technical layers rather than user-visible behavior.
  • Identify the situations where he says the method's up-front work may not pay off, and ask what assumptions those exceptions rely on.
• Context & Thread from Prior Chapters: Chapter 5 identified the parts of a spec; Chapter 6 examined the precision of each requirement sentence. This chapter moves to the size and boundary of the spec as a whole. Keep the earlier edit-task example in mind: a reviewable boundary should help expose decisions like whether a task counts its own unchanged title as a duplicate.

---

2. Reading Review & Reflections

• Prompt Questions:
  1. What tests does Ködel use to decide whether a capability fits one spec?
  2. Why pair complete/reopen but separate create/delete, and how would you split a larger feature into usable increments?
  3. In which situation would you skip or defer a spec, and what would make you revisit that choice?
• User's Answers:
  1. “Can you state it in one sentence, with no ‘and’ in the middle? If you shipped only this, could anyone use it? Can you read the whole spec and disagree with it in ten minutes?”
  2. “hey stayed together because they are the same capability seen from both sides: the same state field, the same transition rule, and one without the other leaves the person stuck. A task that gets completed and never comes back is a task you cannot have checked off by mistake. The pair is the capability; each half alone is half a feature.”
  3. “if its a one off script . I would reconsider if I was going to keep using the script or others needed it”
• Scaffolding & Feedback: All three sizing checks identified. Complete/reopen reasoning is sound; the no-“and” test is a heuristic, since reciprocal actions can comprise one capability. A one-off script fits the author's exception; continued or shared use makes a spec worth considering. Asked for an applied split because create/delete separation and vertical slicing remain unanswered.
• Follow-up Question: A teammate proposes separate database, backend, and UI specs for a To-Do app. What would the first user-usable spec include, and where would deletion belong?
• User's Follow-up Answer: “I think I would work on the ui specs”
• Follow-up Feedback: A UI-only spec is a technical layer, not a usable capability. The first spec should let someone create a task and see it later, crossing UI, behavior, and storage as needed. Deletion can have its own later spec: creation works without it, while deletion introduces confirmation before an irreversible action (PDF pp. 59–60).
• Check for Understanding: In your own words, what can someone do after the first To-Do spec ships?
• User's Further Answer: “I think I would work on the ui specs”; then “then spec out the delete”
• Final Feedback: Deletion as a later, separate spec is right. Starting implementation with the UI is a possible work order, but the first spec must promise a complete user action: add a task and see it in the list later. That includes the necessary UI, behavior, and storage. The repeated UI answer suggests the difference between spec scope and implementation order should be revisited in a real example.

---

3. Chapter Synthesis

• Core Thesis: One spec should cover one usable capability that a person can review as a whole before approving its implementation.
• Key Concepts / Mental Models:
  • One-lap scope: Ask whether the behavior is one coherent capability, useful if shipped alone, and reviewable in roughly ten minutes. The sentence-without-“and” check is a heuristic: create/list and complete/reopen each form a coherent capability despite containing two verbs (PDF pp. 57–59).
  • Complete path: Split a large feature into small increments that each work through the necessary UI, behavior, and storage. A spec for only one technical layer leaves no new action for the user to exercise (PDF pp. 59–60).
  • Boundary check: A split is suspect if one part cannot be demonstrated, two parts depend on each other in both directions, or the same rule appears in both specs (PDF pp. 60–61).
  • Scope by behavior: Complete/reopen share one state transition and belong together. Create/list works before deletion exists; deletion adds distinct rules, including confirmation before an irreversible effect (PDF pp. 58–59).
• Notable Arguments & Evidence: The To-Do example progresses through create/list, complete/reopen, filter, delete, and edit; each adds something a person can use and check. Ködel argues that specs can be wasteful for throwaway scripts, genuine exploration, known one-off fixes, and expiring proofs of concept; a surviving prototype or repeated fix changes that calculation (PDF pp. 60–62). The ten-minute review threshold and cost claims are practical heuristics illustrated by the To-Do example, not measured results presented in this chapter.
• Updates to Prior Understanding: Chapters 5 and 6 addressed what belongs in a spec and how to phrase requirements. Chapter 7 adds the boundary of the document: a reviewable user capability, not a UI, database, or code module. Its architectural boundary questions are deferred to FOCUS Architecture (PDF p. 61).
• Weekly Action Item: Pick one small task-app change. Write the user action it enables in one sentence, check whether it works alone and can be reviewed in ten minutes, then include every layer needed to demonstrate that action in the same spec.