liveBook · Manning

Implementation gap

As explained in Spec-Driven Development

A discrepancy between behavior specified for a system and the behavior or coverage of its implementation.

An implementation gap is a mismatch between intended behavior or design and what the implementation delivers. Review or testing may reveal a missing failure path, an imprecise response, a violated architectural boundary, or a feature declared complete without evidence. In specification-driven development, the gap is also feedback about how intent traveled from the human decision to the specification, implementation, and validation. section 3.1 section 3.2.5

A link feature with an unanswered question

Suppose links expire after a fixed duration. The specification states the duration but never says what happens when someone visits an expired link. An agent must choose that behavior without guidance. If review exposes the omission, specifying the failure path is more durable than adding a branch only in code: the next change can then recover the decision from the specification. The same issue arises when a malformed URL receives an error, but the specification says only “return an error for invalid input” rather than recording the intended status and user-facing message. section 3.2 section 3.1

Attribute a gap to the point where intent was lost, then repair that part of the workflow:

  • Surfacing: a needed behavior was never elicited. Add the missing question to the authoring dialogue. section 3.4.1
  • Capture: the decision was discussed but recorded too vaguely. Strengthen the specification format. section 3.4.1
  • Construction: behavior works, but the implementation violates an intended design boundary. Strengthen standing constraints or structural checks. section 3.4.1
  • Verification: completion was accepted despite a failure found in review or testing. Require repeatable evidence, such as tests or contract checks. section 3.4.1

Correct the current specification before treating the feature as complete, then regenerate or realign the implementation. A direct code edit or ad hoc prompt may be cheaper locally, but it leaves the reason for the correction in code, conversation history, or memory. For recurring gaps, improving only the current feature means paying the same discovery cost again; turn the finding into a standing question, constraint, or verification check where appropriate. section 3.1.3 section 3.1.2 section 3.2.5

Figure 3.3 Implementation gaps should feed back into the part of the SDD workflow where intent was lost.

The feedback-loop diagram locates repairs at the stage where intent escaped, rather than treating every gap as another code patch. section 3.2.5

How Spec-Driven Development covers it

How deep it goes
Classifies gaps by four points of intent loss and prescribes workflow repairs, without detailing code-level implementation.
Examples
Illustrates gaps with expired-link behavior, malformed URL handling, misplaced business rules, and inadequate completion checks.
What it assumes
Assumes familiarity with specifications, agent-generated code, and review or testing; explains the intent-loss stages through concrete failures.
What you can do after
Diagnose/debug with it by locating where intent escaped, correcting the specification, and improving the workflow to prevent recurrence.
How it connects
Connects implementation gaps to specification-driven development, defect leakage, architectural constraints, and deterministic verification.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spec-Driven Development. The section links point to the parts of the book it draws on.