chapter three

3 Keeping Specs Alive

 

This chapter covers

  • How implementation gaps make specs stale
  • Where intent is lost in SDD and how to address it
  • Learning from implementation gaps to improve SDD workflow
  • Treating the SDD workflow as a product through governance
  • How to determine whether a specification is alive
  • Understanding SDD Tooling Landscape

Authoring a specification in SDD is an investment, and like any investment, it pays back over two horizons. The short-term return is alignment between humans and AI on a single feature. The specification captures intent, constrains the agent-generated implementation, and defines how success should be judged. Without that articulated intent, the agent is left to infer too much from code, prompts, and surrounding context.

The longer-term return compounds only as long as the specification remains alive. A specification that still represents the system guides the next feature, helps the agent recover existing behavior without reading the whole codebase, and gives the team a surface it can review and shape instead of steering implementation line by line. A specification that has fallen behind the system still records what was once intended, but it no longer tells the agent or the team how the code should evolve.

3.1 Why specs go stale

3.1.1 Misaligned implementation

3.1.2 The direct fix trap

3.1.3 The cost of repeated spec revision

3.2 Feedback loops

3.2.1 Intent Loss in Surfacing

3.2.2 Intent Loss in Capture

3.2.3 Intent Loss in Construction Constraint

3.2.4 Intent Loss in Outcome Verification

3.2.5 Fine-Tuning the SDD Workflow

3.3 Specifying thoroughly without creating markdown mountains

3.3.1 The specification is one part of the context

3.3.2 Separating the repairs

3.3.3 Invest where deviation is expensive

3.4 Specification governance

3.4.1 Defect leakage and attribution

3.4.2 The governance operating loop

3.5 How alive is a spec?

3.5.1 Control Authority

3.5.2 Specification fidelity

3.5.3 The four states of specification

3.6 Tooling landscape

3.6.1 Taxonomy of spec styles

3.6.2 Framework for evaluating tools

3.7 Summary