Indeed Adam. The two documents problem is real if the spec becomes a permanent, competing source of truth. However, the counter-argument is that SDD + Atomic PRs fundamentally changes the spec’s lifecycle. As noted, if we cap PRs to one concern, the spec is an ephemeral contract, not a permanent architectural document.
The question then pops up is Who retires it? In a mature workflow, the retirement is automated. Tools like Spec Kit’s converge command can be configured to archive or delete the spec files once the PR is merged and verified. The spec exists solely to align the agent during development. Once merged, the code and its tests become the single source of truth. If we treat the spec as a living doc that must stay in sync with production, it fails. But if we treat it as a temporary, auto-deleted verification layer for atomic changes, the drift problem disappears entirely.
Adam Lewis
Product Engineer/Architect navigating the AI revolution
Spec-driven development fixes the failure mode where a thin prompt lets the model invent requirements you never asked for. Regenerating from the spec is cheaper than editing the code only while the code is small enough to throw away. For anything with a real codebase behind it, the code reaches production and the spec drifts out of date within a sprint or two. The spec stays the source of truth once the code exists. I wouldn't bet on that. After that you've got two documents and no way to tell which one the next agent will read.