Chapter 3: Keeping Specs Alive
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
- Short-term value of specifications. Explain how a specification aligns humans and AI on a feature by capturing intent, constraining agent-generated implementation, and defining how success will be judged.
- Long-term value of living specs. Distinguish a specification that still represents the system from one that has fallen behind it, and describe what the team and agent can do with the living specification.
- Implementation gaps as workflow signals. Explain why a gap between intent and implementation should prompt examination of the SDD workflow rather than be treated only as a code patch.
- Hidden intent in implementation. Explain how a direct code change can break an intent that the original implementation satisfies implicitly, using the URL shortener example.
- Specification drift after direct fixes. Explain the longer-term loss when a change is made in code without updating the specification.
- Implementation gap response paths. Distinguish the two responses to a gap found in review or testing and their tradeoff for specification authority.
- Implementation and specification misalignment. Explain why the URL shortener returned a server error for a malformed URL and why patching the validation code alone leaves the specification misaligned with the implementation.
- Delayed cost of direct fixes. Explain why fixing a small implementation gap directly can be attractive now but costly for future changes.
- Recurring gaps as workflow feedback. Explain why revising the specification for each gap is not enough, and describe how a gap can be used to prevent the same category of intent loss from recurring.
- Intent Loss Diagnostic Model. Explain why an implementation gap is feedback about the SDD workflow, and describe how locating the point of intent loss guides the repair.
- Intent Loss During Surfacing. Describe how intent is lost when the authoring dialogue fails to ask about a behavior the human has in mind.
- Intent Loss During Capture. Distinguish capture loss from surfacing loss by explaining how a specification can omit useful detail that the dialogue did elicit.
- Intent Loss During Construction. Explain how an implementation can meet visible behavioral criteria yet violate the intended system structure.
- Intent Loss During Verification. Explain why an agent's claim that an outcome was achieved remains unchecked without required, repeatable evidence.
- Unsurfaced intent in authoring. Explain how intent can be lost during the authoring conversation even when the resulting specification accurately reflects what was discussed. Use the expiring-link example to distinguish missing intent from an agent misinterpreting stated intent.
- Workflow driven failure path questions. Describe the durable fix: make the authoring workflow ask about failure paths rather than relying on the author to remember. Explain how change-proposal guidance can encode those questions.
- Intent loss during capture. Explain how a conversation can establish the intended behavior while the written specification loses important details, and why a richer format can prevent that loss.
- Surfacing versus capture repairs. Distinguish missing behavior caused by an unasked question from missing behavior caused by a spec that failed to record the answer, and identify the corresponding repair.
- Construction intent loss. Explain how a feature can pass acceptance tests yet violate the URL shortener’s standing construction approach.
- Durable construction constraints. Explain why standing construction constraints belong in project-level context rather than being repeated in each conversation.
- Evidence before implementation. Explain why a declared outcome needs a deterministic check, and trace the test-first sequence from writing and running a failing check to implementing the behavior and rerunning that check.
- Observable checks over checkboxes. Explain how a weak completion criterion permits reward hacking and how an observable check better encodes the intended outcome.
- Gap-specific workflow repairs. Trace an implementation gap to where intent was lost and describe the corresponding workflow repair: improve authoring questions, strengthen specification capture, enforce construction constraints, or require evidence through deterministic verification.
- Feature fixes versus recurrence prevention. Distinguish correcting the current feature from improving the workflow when the same class of gap is likely to recur. Explain how an observed defect can serve as a signal about a missing workflow question or ineffective constraint.
- Thoroughness and authoring burden. Explain why stronger specifications reduce deviation, and why repeatedly rewriting recurring concerns can cause teams to bypass the specification.
- Feature specification boundaries. Distinguish what belongs in a feature specification from concerns that apply across the system.
- Feature specs and standing context. Explain why a feature specification is only part of the execution harness’s context and why recurring concerns belong in standing context.
- Surfacing and capture repairs. Distinguish a surfacing repair from a capture repair: change the dialogue and Propose-step questions when an issue is not raised, but change the specification format when a discussed decision is recorded too vaguely.
- Construction and verification repairs. Distinguish construction repairs from verification repairs: make repeatedly ignored boundaries durable through standing constraints and checks, and require evidence before accepting an agent's claim of completion.
- Proportional rigor for deviations. Explain how the cost of a deviation and how often a concern recurs determine the rigor it deserves. Contrast high-risk concerns with a one-off, low-risk formatting change.
- Reusable safeguards for recurring risks. Explain why teams should encode recurring high-risk concerns once and have the workflow apply the appropriate rigor wherever relevant, rather than adding a burden to each feature.
- SDD Workflow as Product. Explain why the team should treat the SDD workflow inside the Intent Harness as a product, and identify what it produces.
- Governance of Escaped Gaps. Explain why an escaped implementation gap calls for examining the workflow as well as the generated code.
- Intent loss attribution. Distinguish surfacing, capture, construction, and verification losses by the implementation gaps each tends to produce.
- Attribution guided workflow repair. Explain how the attributed loss determines which part of the SDD workflow to improve, rather than prompting a generic fix.
- Governance loop for intent loss. Trace how the governance loop turns an observed implementation gap into a specification repair and, once the problem is understood, a tested workflow improvement.
- Outcome measures over phase speed. Explain why time spent specifying or implementing does not, by itself, measure SDD effectiveness.
- Initial alignment and lasting alignment. Distinguish time-to-aligned implementation from alignment regression and explain why both matter.
- Bypass and false completion signals. Describe what specification bypass and false-positive completions reveal about an SDD workflow.
- Living specification criterion. Explain why a specification is alive only if it can still steer the system, rather than merely existing or having been edited recently.
- Authority and fidelity distinction. Distinguish control authority from specification fidelity, and explain why a specification can have one without the other.
- Specification control authority. Explain that a specification has control authority when behavior changes pass through it before implementation, so changing the spec changes the system in the intended direction.
- Direct changes and context debt. Explain why changing code directly removes the specification's control authority, even if the change is correct and the spec is updated afterward. Describe the resulting cost to future work.
- Specification fidelity and reliability. Explain what specification fidelity measures and why it matters to agents and teams making future changes.
- Staleness and incompleteness. Distinguish the two ways fidelity can fail and describe the consequence of each.
- Fidelity versus control authority. Explain why specification fidelity and control authority must be assessed separately, including how either can exist without the other.
- Four specification states. Explain how control authority and fidelity combine to produce authoritative, underspecified, reconciled, and decorative specifications.
- Path toward authoritative specifications. Explain why a team may start with a reconciled specification and how it can move toward an authoritative one.
- Ongoing specification repair. Explain how to notice declining authority or fidelity and use implementation gaps to repair the workflow rather than merely update a document once.
- Tooling and specification longevity. Explain why an SDD tool should be evaluated by its support for keeping specifications alive, not just by the quality of the initial document or the way the tool is packaged.
- Specification style trade-offs. Explain how the taxonomy helps a team choose a specification style for its context rather than selecting a tool because its output looks convincing.
- Intent-preserving specification detail. Justify a level of detail that preserves decisions the agent must not invent without making the specification too large to review.
- Tool fit and granularity. Explain why the criteria are lenses for team fit rather than a scorecard, and describe the tradeoff in a tool’s default specification size.
- Standing guidance and system view. Describe why a tool should carry recurring guidance outside feature specs and provide a coherent view of the system’s current state.
- Evidence of implementation alignment. Explain how to evaluate a tool’s support for checking that implementation matches the specification.
- Workflow extensibility from gaps. Explain why an SDD tool needs to let teams adapt their workflow as they discover recurring implementation gaps.
What it builds on
- What is a specification (chapter 2) · The definition of a specification in SDD.
- Spec-driven development workflow (chapter 2) · The SDD workflow in which a specification guides implementation.
- Project Configuration (chapter 2) · Project configuration as part of setting up an SDD project.
- Context debt and the return to manual mode (chapter 2) · The concept of context debt.
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.
- Short-term value of specifications: Explain how a specification aligns humans and AI on a feature by capturing intent, constraining agent-generated implementation, and defining how success will be judged.
Why it matters: This is the immediate payoff for the effort of writing a specification. - Long-term value of living specs: Distinguish a specification that still represents the system from one that has fallen behind it, and describe what the team and agent can do with the living specification.
Why it matters: A spec remains useful for future features only if it continues to describe the system people are changing. - Implementation gaps as workflow signals: Explain why a gap between intent and implementation should prompt examination of the SDD workflow rather than be treated only as a code patch.
Why it matters: Looking beyond a local code fix helps prevent the same loss of intent from recurring.
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.
- Hidden intent in implementation: Explain how a direct code change can break an intent that the original implementation satisfies implicitly, using the URL shortener example.
Why it matters: Code alone may not reveal the business intent a later change must preserve. - Specification drift after direct fixes: Explain the longer-term loss when a change is made in code without updating the specification.
Why it matters: A fix that works today can make later changes harder to guide reliably. - Implementation gap response paths: Distinguish the two responses to a gap found in review or testing and their tradeoff for specification authority.
Why it matters: The cheaper-looking response to a small gap determines where the intent behind its correction is kept.
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.
- Implementation and specification misalignment: Explain why the URL shortener returned a server error for a malformed URL and why patching the validation code alone leaves the specification misaligned with the implementation.
Why it matters: A working patch does not help the next agent if the specification still omits the decision behind it.
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.
- Gradual specification drift: Describe how a specification can fall behind through small, locally reasonable changes rather than an explicit decision to abandon it.
Why it matters: Small omissions add up even when no single change seems consequential. - Delayed cost of direct fixes: Explain why fixing a small implementation gap directly can be attractive now but costly for future changes.
Why it matters: The time saved on a small fix can become intent-recovery work on the next change.
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.
- Specification authority over fixes: Explain why a behavior discovered through an implementation gap should be added to the specification before the implementation is considered complete or realigned.
Why it matters: Keeping the spec current lets it remain the basis for correcting the implementation. - Recurring gaps as workflow feedback: Explain why revising the specification for each gap is not enough, and describe how a gap can be used to prevent the same category of intent loss from recurring.
Why it matters: Fixing the process behind recurring gaps makes the spec-first path more sustainable under delivery pressure.
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.
- Intent Loss Diagnostic Model: Explain why an implementation gap is feedback about the SDD workflow, and describe how locating the point of intent loss guides the repair.
Why it matters: Finding where intent was lost helps you address the workflow failure behind an implementation gap. - Intent Loss During Surfacing: Describe how intent is lost when the authoring dialogue fails to ask about a behavior the human has in mind.
Why it matters: A specification cannot preserve an intended behavior that the authoring conversation never brought out. - Intent Loss During Capture: Distinguish capture loss from surfacing loss by explaining how a specification can omit useful detail that the dialogue did elicit.
Why it matters: Discussing a decision is not enough if the specification drops the details the agent needs. - Intent Loss During Construction: Explain how an implementation can meet visible behavioral criteria yet violate the intended system structure.
Why it matters: Passing visible behavior checks does not establish that the agent respected the intended architecture. - Intent Loss During Verification: Explain why an agent's claim that an outcome was achieved remains unchecked without required, repeatable evidence.
Why it matters: A reported outcome is not verified merely because the agent says it works.
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.
- Unsurfaced intent in authoring: Explain how intent can be lost during the authoring conversation even when the resulting specification accurately reflects what was discussed. Use the expiring-link example to distinguish missing intent from an agent misinterpreting stated intent.
Why it matters: Recognizing an unasked question prevents you from treating an unspecified decision as an implementation misunderstanding. - Workflow driven failure path questions: Describe the durable fix: make the authoring workflow ask about failure paths rather than relying on the author to remember. Explain how change-proposal guidance can encode those questions.
Why it matters: Encoding a useful question in the workflow makes it less likely that the next feature will omit the same kind of decision.
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.
- Intent loss during capture: Explain how a conversation can establish the intended behavior while the written specification loses important details, and why a richer format can prevent that loss.
Why it matters: A clear discussion cannot guide execution if its decisions disappear from the spec. - Specification format adequacy: Describe how to decide whether a tool's existing specification format needs changing, using OpenSpec's scenario blocks as the example.
Why it matters: Checking what the existing format preserves avoids unnecessary customization while still protecting important details. - Surfacing versus capture repairs: Distinguish missing behavior caused by an unasked question from missing behavior caused by a spec that failed to record the answer, and identify the corresponding repair.
Why it matters: Finding where the detail was lost directs the team to fix the dialogue or the spec format rather than treating every omission alike.
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.
- Construction intent loss: Explain how a feature can pass acceptance tests yet violate the URL shortener’s standing construction approach.
Why it matters: Passing tests can hide a departure from the project’s intended design. - Durable construction constraints: Explain why standing construction constraints belong in project-level context rather than being repeated in each conversation.
Why it matters: A durable home for standing guidance reduces reliance on someone remembering to repeat it.
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.
- Evidence before implementation: Explain why a declared outcome needs a deterministic check, and trace the test-first sequence from writing and running a failing check to implementing the behavior and rerunning that check.
Why it matters: A passing, predeclared check provides stronger evidence of the intended outcome than an implementation claim. - Redirect status as intent: Distinguish the consequences of 302 and 301 redirects for the URL shortener, and explain why the status code must be decided in the specification rather than invented in a task or test.
Why it matters: A precise test can still verify the wrong outcome if it asserts a business decision the specification never made. - Observable checks over checkboxes: Explain how a weak completion criterion permits reward hacking and how an observable check better encodes the intended outcome.
Why it matters: The quality of the completion check shapes what the agent is likely to deliver.
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.
- Gap-specific workflow repairs: Trace an implementation gap to where intent was lost and describe the corresponding workflow repair: improve authoring questions, strengthen specification capture, enforce construction constraints, or require evidence through deterministic verification.
Why it matters: Finding where intent escaped helps prevent the same kind of implementation gap from recurring. - Feature fixes versus recurrence prevention: Distinguish correcting the current feature from improving the workflow when the same class of gap is likely to recur. Explain how an observed defect can serve as a signal about a missing workflow question or ineffective constraint.
Why it matters: A local fix resolves one defect, while a workflow improvement can prevent its recurrence.
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.
- Thoroughness and authoring burden: Explain why stronger specifications reduce deviation, and why repeatedly rewriting recurring concerns can cause teams to bypass the specification.
Why it matters: A specification needs enough detail to guide the work without making every feature costly to describe. - Feature specification boundaries: Distinguish what belongs in a feature specification from concerns that apply across the system.
Why it matters: Keeping feature-specific intent in the feature spec avoids needless repetition without abandoning thoroughness.
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.
- Feature specs and standing context: Explain why a feature specification is only part of the execution harness’s context and why recurring concerns belong in standing context.
Why it matters: A concise feature spec can still guide aligned implementation when reusable context is supplied elsewhere. - Forms of standing context: Describe what project configuration, skills, hooks and deterministic checks, and Architecture Decision Records contribute as reusable context.
Why it matters: Choosing a suitable home for recurring guidance reduces duplication and makes important checks less dependent on a spec author’s memory.
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.
- Surfacing and capture repairs: Distinguish a surfacing repair from a capture repair: change the dialogue and Propose-step questions when an issue is not raised, but change the specification format when a discussed decision is recorded too vaguely.
Why it matters: The right repair depends on whether the decision was never raised or was raised but poorly recorded. - Construction and verification repairs: Distinguish construction repairs from verification repairs: make repeatedly ignored boundaries durable through standing constraints and checks, and require evidence before accepting an agent's claim of completion.
Why it matters: Constraints address how agents build; evidence addresses whether the result can be accepted as complete.
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.
- Proportional rigor for deviations: Explain how the cost of a deviation and how often a concern recurs determine the rigor it deserves. Contrast high-risk concerns with a one-off, low-risk formatting change.
Why it matters: Matching rigor to risk protects consequential work without overcomplicating small changes. - Reusable safeguards for recurring risks: Explain why teams should encode recurring high-risk concerns once and have the workflow apply the appropriate rigor wherever relevant, rather than adding a burden to each feature.
Why it matters: Reusable safeguards let teams maintain rigor without repeatedly rebuilding it for each 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.
- SDD Workflow as Product: Explain why the team should treat the SDD workflow inside the Intent Harness as a product, and identify what it produces.
Why it matters: Treating the workflow as a product makes its users, output, and quality problems visible. - Governance of Escaped Gaps: Explain why an escaped implementation gap calls for examining the workflow as well as the generated code.
Why it matters: Fixing code alone can leave the workflow problem that allowed the gap to escape unexamined.
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.
- Intent loss attribution: Distinguish surfacing, capture, construction, and verification losses by the implementation gaps each tends to produce.
Why it matters: Finding where intent was lost gives you a better starting point than treating every gap as the same kind of defect. - Attribution guided workflow repair: Explain how the attributed loss determines which part of the SDD workflow to improve, rather than prompting a generic fix.
Why it matters: The right diagnosis helps prevent repeated fixes that leave the underlying workflow gap in place.
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.
- Governance loop for intent loss: Trace how the governance loop turns an observed implementation gap into a specification repair and, once the problem is understood, a tested workflow improvement.
Why it matters: It distinguishes fixing one feature from improving the workflow that allowed the gap. - Small sustainable governance habit: Justify keeping governance changes small and routine rather than trying to resolve every intent-loss problem at once.
Why it matters: A lightweight habit is more likely to survive the pressure to deliver features. - Outcome measures over phase speed: Explain why time spent specifying or implementing does not, by itself, measure SDD effectiveness.
Why it matters: Optimizing a fast-looking phase can hide rework or skipped verification. - Initial alignment and lasting alignment: Distinguish time-to-aligned implementation from alignment regression and explain why both matter.
Why it matters: A feature must both reach alignment promptly and remain aligned as the system changes. - Bypass and false completion signals: Describe what specification bypass and false-positive completions reveal about an SDD workflow.
Why it matters: These signals show when changes bypass the specification or completion lacks demonstrable evidence.
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.
- Living specification criterion: Explain why a specification is alive only if it can still steer the system, rather than merely existing or having been edited recently.
Why it matters: This criterion keeps attention on whether the spec is useful for the next change, not just whether it is up to date on paper. - Authority and fidelity distinction: Distinguish control authority from specification fidelity, and explain why a specification can have one without the other.
Why it matters: Separating these properties helps identify whether the spec has lost influence over changes, accuracy about the system, or both.
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.
- Specification control authority: Explain that a specification has control authority when behavior changes pass through it before implementation, so changing the spec changes the system in the intended direction.
Why it matters: It tells you whether the spec actually steers development rather than merely describes it. - Direct changes and context debt: Explain why changing code directly removes the specification's control authority, even if the change is correct and the spec is updated afterward. Describe the resulting cost to future work.
Why it matters: A small direct fix can create a larger burden when later work can no longer rely on the spec as the source of intended behavior.
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.
- Specification fidelity and reliability: Explain what specification fidelity measures and why it matters to agents and teams making future changes.
Why it matters: A spec can guide future changes only if it gives people and agents a trustworthy picture of the system. - Staleness and incompleteness: Distinguish the two ways fidelity can fail and describe the consequence of each.
Why it matters: Checking whether a spec is current is not enough if its gaps still let an agent make consequential choices. - Fidelity versus control authority: Explain why specification fidelity and control authority must be assessed separately, including how either can exist without the other.
Why it matters: Making the spec mandatory does not help enough if it leaves decisions unspecified, and an accurate after-the-fact record does not direct change.
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.
- Four specification states: Explain how control authority and fidelity combine to produce authoritative, underspecified, reconciled, and decorative specifications.
Why it matters: The two dimensions show why a current-looking spec is not necessarily safe to use to drive change. - Underspecification regeneration test: Describe how regenerating an implementation from the same specification can reveal underspecification and how the team should respond.
Why it matters: A disciplined spec-first process can still yield inconsistent behavior if the spec leaves important choices open. - Path toward authoritative specifications: Explain why a team may start with a reconciled specification and how it can move toward an authoritative one.
Why it matters: A useful spec need not become authoritative in one step, but the team should be clear about whether code still leads change. - SDD workflow levels: Distinguish spec-first, spec-anchored, and spec-as-source by the specification's role after the initial build, and relate each to possible specification states.
Why it matters: The workflow's name matters less than whether the spec continues to guide changes accurately. - Ongoing specification repair: Explain how to notice declining authority or fidelity and use implementation gaps to repair the workflow rather than merely update a document once.
Why it matters: A spec stays trustworthy through the way the team handles changes and gaps, not through a one-time documentation update.
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.
- Tooling and specification longevity: Explain why an SDD tool should be evaluated by its support for keeping specifications alive, not just by the quality of the initial document or the way the tool is packaged.
Why it matters: A tool can help with the first implementation yet leave the team without a useful specification as the product changes. - Range of SDD tools: Describe how SDD tools differ in what they help authors create, how much workflow they prescribe, and how they are packaged.
Why it matters: Recognizing these differences helps you compare what tools actually support without assuming they all serve the same purpose.
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.
- Specification style trade-offs: Explain how the taxonomy helps a team choose a specification style for its context rather than selecting a tool because its output looks convincing.
Why it matters: It gives you a way to evaluate tools against your team's needs instead of judging their output by appearance. - Requirement structure and fidelity: Distinguish free-form, structured, and machine-parseable requirements by their effects on ease of authoring, interpretation, and capture fidelity.
Why it matters: The format determines whether important decisions are captured or left for the agent to interpret. - Feature and system organization: Compare per-feature, evolving system, and hybrid organization of specs in terms of understanding a change and understanding current behavior.
Why it matters: How specs are organized affects whether the team can see both the intended change and the system it will change. - Intent-preserving specification detail: Justify a level of detail that preserves decisions the agent must not invent without making the specification too large to review.
Why it matters: A useful spec must constrain consequential guesses while remaining practical for people to review. - Evidence of implementation alignment: Explain why a specification's claims need evidence of implementation alignment and how spec styles differ in supporting that evidence.
Why it matters: Checks help establish whether implementation matches intent rather than merely repeating what the spec declares. - Contributor access to intent: Explain how a spec's location and structure can include or exclude people who need to contribute intent.
Why it matters: Intent can be lost before implementation if the people who hold it cannot contribute to the spec.
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.
- Tool fit and granularity: Explain why the criteria are lenses for team fit rather than a scorecard, and describe the tradeoff in a tool’s default specification size.
Why it matters: The best-looking generated spec is not necessarily one your team can use and keep current. - Standing guidance and system view: Describe why a tool should carry recurring guidance outside feature specs and provide a coherent view of the system’s current state.
Why it matters: Shared rules and an accurate system-wide view let future work build on durable context rather than reconstructing it. - Existing backlog context: Explain why backlog integration matters when creating specifications.
Why it matters: A specification starts stronger when it carries forward decisions and details the team has already recorded. - Architecture and adoption fit: Describe how multi-repository support and brownfield suitability affect whether a tool fits an existing system.
Why it matters: A tool that assumes one repository or a fresh start may fail even if its spec-generation features look strong. - Evidence of implementation alignment: Explain how to evaluate a tool’s support for checking that implementation matches the specification.
Why it matters: A finished-looking implementation is not proof that the specified outcome was delivered. - Workflow extensibility from gaps: Explain why an SDD tool needs to let teams adapt their workflow as they discover recurring implementation gaps.
Why it matters: Keeping specs alive requires improving the workflow when experience exposes repeated losses.
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
- Architect shapes the how (chapter 4) · A specification is only one part of the context available to an agent.
- First slice: each role contributes its part (chapter 4) · The distinction between a feature specification and other context supplied to the agent.
- Engineer authors the tasks (chapter 4) · The idea of using feedback to improve specification governance.
Concepts explained in this chapter
- deterministic checkDeterministic verification is verification based on repeatable checks that produce evidence of whether a specified outcome has been achieved.
- control authorityControl authority is the property of a specification whereby changing it directs system behavior and implementation in the intended direction.
- implementation gapA discrepancy between behavior specified for a system and the behavior or coverage of its implementation.
- implementation constraintAn implementation constraint is a restriction or boundary that limits how a software solution may be designed or built.
- specificationA structured description of software intent, requirements, implementation constraints, and expected outcomes.
- intent lossIntent loss is the failure to preserve a human's intended meaning, requirements, or constraints across the stages of software development.
- authoritative specificationAn authoritative specification is a specification with high control authority and high fidelity that governs system changes while accurately representing the application.
- decorative specificationA decorative specification is a specification that neither governs system changes nor accurately represents the code.
- reconciled specificationA reconciled specification is a specification reconstructed from an existing application that accurately describes the system but does not govern its changes.
- regeneration testA regeneration test checks whether regenerating an implementation from the same specification reproduces the same behavior.
- spec-anchoredA spec-anchored workflow keeps the specification in the feature lifecycle and updates it alongside the evolving implementation.
- spec-as-sourceA spec-as-source workflow treats the specification as the primary editable artifact from which an agent generates or updates the implementation.
- spec-firstA spec-first workflow creates a specification before implementation to guide an initial build without necessarily keeping the specification central afterward.
- underspecified specificationAn underspecified specification is a specification that governs changes but omits enough intent or detail to constrain implementation reliably.
- specification formatA specification format is a defined structure and notation for recording requirements and decisions with sufficient precision for implementation.
- contextInformation supplied to an AI coding agent to guide its understanding and work.
- specification-driven developmentA software development approach in which specifications produced through human–AI dialogue guide implementation.
- alignment regressionThe loss of previously achieved behavioral alignment as an implementation evolves and new features are added.
- false positiveA result incorrectly judged to satisfy a condition when it does not.
- governance loopA recurring process for detecting intent loss, correcting specifications and implementations, and improving the development workflow.
- specification bypassA change made directly to code without first being represented in the governing specification.
- time-to-aligned implementationThe elapsed time from an idea to the first implementation that satisfies intended behavior, construction constraints, and verification evidence.
- specification-to-implementation alignmentSpecification-to-implementation alignment is the degree to which an implementation conforms to the behavior and constraints expressed in its specification.
- granularitySpecification granularity is the level of detail at which a specification describes required behavior and implementation constraints.
- requirements structureRequirements structure is the organization and formalization of requirements statements, including their grammar and behavioral expression.
- scope of authorshipScope of authorship is the set of participants, roles, and locations permitted to create or contribute to a specification.
- specification organizationThe arrangement of specifications across features, system state, or both.
- verifiability mechanismA verifiability mechanism is a process or technical facility for checking alignment between a specification and an implementation.
- ai coding assistantAn AI-powered tool that interprets development instructions and performs coding tasks.
- structured conversationAn interaction structured to elicit missing information and capture software intent in a specification.
- intentIntent is the actionable expression of purpose for a specific change, concrete enough to guide implementation and verification.
- intent harnessA higher-level harness that helps humans and agents articulate intent and produce durable artifacts that guide execution.
- OpenSpecA specification-driven development tool that provides workflows and artifacts for proposing, applying, and archiving changes.
- specification gapMissing or incomplete information in a specification that can cause an implementation to diverge from the intended behavior.
- execution harnessAn agent harness specialized for independently carrying out tasks and generating implementations or other work products.
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.
