liveBook · Manning

Chapter 3: Keeping Specs Alive

What you will learn in chapter 3 of Spec-Driven Development

The introduction explains why specifications must stay aligned with the system to keep guiding agent-generated work, and why implementation gaps should inform improvements to the SDD workflow.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The introduction explains why specifications must stay aligned with the system to keep guiding agent-generated work, and why implementation gaps should inform improvements to the SDD workflow.

Key terms: specification, intent, agent-generated implementation, alive, longer-term return, implementation gaps, SDD workflow, primary control surface

3.1 Why specs go stale

This section explains how bypassing a specification to fix implementation gaps can break implicit requirements and leave the specification out of date.

Key terms: business intent, shortcode reassignment, specification, durable context, single source of truth, implementation gap, misaligned implementation, ad hoc prompt, specification authoritative

3.1.1 Misaligned implementation

A URL-shortener example shows how an underspecified requirement can produce faulty behavior and how a code-only fix leaves the specification stale.

Key terms: specification, malformed URL, validation, misaligned implementation

3.1.2 The direct fix trap

The section explains how locally convenient fixes make specifications stale and shift the cost of recovering intent to future work.

Key terms: specification, durable context, direct fix, future alignment, control surface

3.1.3 The cost of repeated spec revision

This section explains why correcting a spec for each implementation gap is necessary but insufficient: recurring gaps should also drive improvements to the SDD workflow.

Key terms: implementation gap, specification, regenerated or realigned, implementation gaps, feedback, SDD workflow, intent loss

3.2 Feedback loops

This section uses implementation gaps to identify four points where an SDD workflow can lose intent before code is produced or accepted.

Key terms: SDD workflow, Intent Harness, intent loss, implementation gaps, surfacing, authoring dialogue, intent, capture, specification, malformed URL

3.2.1 Intent Loss in Surfacing

This section explains how intent can be lost before it reaches a specification and how to make the authoring workflow surface missing failure-path decisions.

Key terms: intent loss in surfacing, authoring conversation, failure path, authoring dialogue, OpenSpec, config.yaml, proposal.md

3.2.2 Intent Loss in Capture

This section explains how intent can be lost when a specification fails to retain details already established in conversation, and how to identify the right repair.

Key terms: intent loss in capture, specification format, bare prose format, Gherkin, OpenSpec, scenario blocks, WHEN/THEN, surfacing, capture, dialogue

3.2.3 Intent Loss in Construction Constraint

The section shows how an agent can deliver working behavior while losing construction intent, and how durable project-level constraints prevent that loss.

Key terms: construction intent, standing construction approach, acceptance tests, standing construction constraints, project-level context, durable specification context

3.2.4 Intent Loss in Outcome Verification

The section shows how to prevent intent loss in outcome verification by defining observable evidence before implementation and using it to decide whether a feature is complete.

Key terms: outcome verification, deterministic check, completion gate, test-first evidence, 302, 301, capture loss, click analytics, reward hacking, reward shaping

3.2.5 Fine-Tuning the SDD Workflow

This section shows how to use implementation gaps to repair the stage of the SDD workflow where intent was lost, rather than only fixing the current feature.

Key terms: intent loss, authoring dialogue, specification format, standing constraints, deterministic verification, implementation gaps, learning signals, current specification, workflow

3.3 Specifying thoroughly without creating markdown mountains

The section explains how to make specifications thorough enough to reduce deviation without making feature authors repeatedly document system-wide concerns.

Key terms: deviation, missing intent, demonstrations, recurring concern, feature specification, engineered context, user need, rule, boundary, demonstration

3.3.1 The specification is one part of the context

This section explains how standing context keeps feature specifications thorough without making them repetitive or lengthy.

Key terms: execution harness, standing context, feature specification, project configuration, skills, hooks, deterministic checks, Architecture Decision Records

3.3.2 Separating the repairs

The section matches four kinds of intent loss to repairs in different parts of the SDD workflow.

Key terms: surfacing repair, capture repair, Propose step, specification format, construction repair, standing construction context, reusable skills, structural checks, verification repair, deterministic evidence

3.3.3 Invest where deviation is expensive

This section explains how to match specification rigor to the cost and recurrence of deviations without burdening every feature.

Key terms: cost of deviation, proportional, deterministic check, strong demonstration, traceability, recurring high-risk concerns, workflow, authoring path

3.4 Specification governance

This section frames the SDD workflow as a product whose output is durable context, and governance as examining that workflow when implementation gaps escape.

Key terms: SDD workflow, Intent Harness, Execution Harness, durable, executable context, implementation gap, governance, intent

3.4.1 Defect leakage and attribution

This section shows how to trace an implementation gap to the point where intent was lost and use that attribution to repair the right part of the SDD workflow.

Key terms: defect leakage, intent loss, surfacing loss, capture loss, construction loss, verification loss, attribution, standing questions, specification format, project-level constraints

3.4.2 The governance operating loop

This section explains a lightweight routine for correcting intent loss and identifies outcome-oriented signals for judging whether the SDD workflow keeps implementations aligned.

Key terms: SDD governance loop, inner loop, intent loss, backtest, Intent Harness, small attributable changes, governance loop, time spent specifying, time spent implementing, outcome-oriented

3.5 How alive is a spec?

Defines an alive specification as one that can guide the next change, then distinguishes the two properties that make this possible.

Key terms: alive, steer the system, control authority, specification fidelity

3.5.1 Control Authority

The section explains how a specification retains control authority by driving behavior changes, and how direct code changes undermine that authority even when the spec is updated afterward.

Key terms: control authority, upstream of the code, control surface, record, context debt

3.5.2 Specification fidelity

This section defines specification fidelity, shows how staleness and incompleteness undermine it, and distinguishes fidelity from control authority.

Key terms: specification fidelity, high-fidelity specification, low-fidelity specification, staleness, incompleteness, control authority, alive specification

3.5.3 The four states of specification

This section uses control authority and fidelity to distinguish four states of a specification and explains how workflows can move toward—and sustain—the authoritative state.

Key terms: control authority, fidelity, Authoritative Specification, Underspecified Specification, Reconciled Specification, Decorative Specification, regeneration test, underspecification, brownfield, spec-first

3.6 Tooling landscape

This section introduces the variety of SDD tools and argues that they should be judged by how well they keep specifications useful throughout change, not by their packaging.

Key terms: keep specifications alive, standing context, verification, brownfield adoption, PRD-style documents, user stories, acceptance criteria, MCP servers, workflow extensions

3.6.1 Taxonomy of spec styles

This section compares specification styles by the trade-offs they create for preserving intent, guiding agents, enabling verification, and including contributors.

Key terms: specification format, structure, location, granularity, organization, taxonomy, free-form user stories, acceptance criteria, EARS, Gherkin

3.6.2 Framework for evaluating tools

This section offers practical lenses for choosing SDD tools that keep specifications useful as a system and its workflow evolve.

Key terms: lenses, reasonable granularity defaults, living specifications, top-level steering support, top-level view of current state, standing context, durable context, backlog integration, intent, backlog items

3.7 Summary

The chapter closes by showing how teams keep specifications current, use implementation gaps to improve the workflow, and judge whether a spec can guide future work.

Where this is used later

Concepts explained in this chapter

← Chapter 2: Writing Your First Specification Chapter 4: Collaborating Across Product, Architecture, and Engineering →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.