Living Specs vs Static Plans

Six weeks after a checkout feature ships, a bug fix changes how a discount code interacts with a gift card — an edge case nobody wrote down when the feature was specified, because nobody hit it until a customer did. The fix is two lines. The spec file that generated the original feature, still sitting in the repository under `specs/014-checkout-discounts/spec.md`, now describes behavior the code no longer has. A reviewer asks, almost as an aside, whether the PR should update the spec too. Nobody has a confident answer. The PR merges without touching it, because shipping the fix is the actual job and the spec update feels like homework nobody assigned.

That small, unresolved moment repeats constantly wherever spec-driven development has taken hold, and it is bigger than it looks. It is not a process gap that better discipline would close. It is a real disagreement about what a specification is for, and the tools teams already use have quietly picked different answers without ever putting the question on the table. The previous chapters in this volume built the vocabulary and the workflow — the constitution, the specify-plan-tasks sequence Chapter 5 laid out, the shift from prompt phrasing to structured intent Chapter 2 traced. Both flagged this exact tension in passing and moved on. This chapter stops and takes it on directly, because the honest answer is not a rule — it is a tradeoff worth naming precisely.

Three tools, three quiet answers

In the most careful public treatment of this question to date, Thoughtworks technologist Birgitta Böckeler examined three spec-driven tools and found each one had already made an implicit choice about spec permanence. She names three levels: spec-first, where a spec is written, used to generate the feature, and then effectively done its job; spec-anchored, where the spec is kept after the task completes and continued as a live reference for evolution and maintenance; and spec-as-source, where the spec becomes the primary artifact a human edits, and code is regenerated from it rather than hand-edited directly.

Kiro, AWS’s IDE-integrated tool, sits closest to spec-first: a feature gets a requirements.md, a design.md, and a tasks.md, structured with EARS-style acceptance criteria, and once the tasks are executed the documents read like planning residue rather than a maintained contract. GitHub’s spec-kit aspires to more — it ships a `/speckit.converge` command explicitly meant to assess the codebase against the spec and append whatever drifted as new tasks, which is a spec-anchored ambition. But Böckeler’s assessment is that in practice it functions closer to spec-first anyway, because specs live in per-feature branch directories tied to individual change requests, which is a spec-first shape wearing spec-anchored language.

Tessl takes the most radical position: spec-as-source, where a spec file carries a `@generate` directive, code produced from it is marked as generated and not meant for direct human edits, and the framework’s own materials describe specs as living alongside the app as it evolves rather than being retired once. As of its most recent public description the framework is still in closed beta, and its own documentation stops short of promising continuous, automatic validation between spec and code — the aspiration is real, but as of 2026 it is closer to a bet than a mature, load-bearing practice.

A choice nobody is making on purpose

None of these three tools argues its position out loud. A team adopts whichever one fits its workflow, inherits its default, and only discovers the implicit answer months later, in exactly the moment the checkout example opened with — a reviewer asking whether a spec needs updating, and nobody having a policy to point to. The disagreement is not between the tools and their users. It is between two entirely defensible views of what a specification is, and both deserve to be argued at full strength rather than one being waved through as obviously right.

The case for keeping it alive

A spec that stays current is a form of Decision Memory — Volume II’s name for a durable, queryable record of why a choice was made — held at feature grain instead of individual-session grain. For as long as a feature exists, a maintained spec answers a question that otherwise turns into archaeology: not just what the checkout flow does, but why the discount-and-gift-card interaction works the way it does, for the next engineer, the next AI session, or the same engineer eighteen months later with no memory of the original tradeoff. That is real, compounding value, and it is the strongest argument spec-anchored and spec-as-source proponents have.

The failure mode on the other side is what makes the living-spec case sharper than it first sounds. A spec allowed to drift silently out of sync with the code it once generated does not fade into irrelevance the way an old planning doc does — it keeps looking like ground truth. A new engineer, or a new AI session reading it as context, has no visible signal that the discount-and-gift-card behavior described no longer matches what ships. The mistake that follows is not a shrug; it is a confidently wrong implementation built on a document nobody flagged as untrustworthy. A specification’s whole value proposition is that it can be trusted at a glance. Once that stops being true, it is actively worse than having no spec at all, because no spec at least forces a reader back to the code.

The case for letting it go

The counter-case is not laziness dressed up as principle. Code changes for reasons a spec never anticipated and often should not have to anticipate: a bug fix uncovered in production, a dependency upgrade that changes a library’s contract, an edge case nobody could have specified in advance because nobody knew it existed. Demanding that every such change also produce a synchronized update to a formal specification document turns every small fix into two changes instead of one, and the second change carries no direct product value — it is pure maintenance tax, paid to keep two representations of the same behavior in agreement.

That tax is exactly the one the field already tried to pay once, under a different name, and rejected for good reason. Comprehensive up-front documentation kept in permanent lockstep with a changing system was standard practice before the Agile Manifesto explicitly valued working software over comprehensive documentation, and the practice fell out of favor because the discipline it demanded rarely survived contact with a deadline — teams either paid the tax honestly and slowed down, or skipped it and kept a document nobody trusted, which is the same stale-spec failure mode from the other side. Treating a spec as disposable — genuinely valuable for the one act of generating the first working version, safely set aside once the code becomes its own reference — sidesteps that tax entirely, at the cost of losing the why once the moment of generation passes.

A living spec is a second system that must always agree with the first. A disposable one is a bet that the code will explain itself.

What the tension actually depends on

Neither case wins outright, and a rigorous answer resists collapsing into a universal rule. Three factors do most of the work in tilting a specific decision one way or the other: how volatile and how central the thing being specified is, how many people or independent AI sessions need to reconstruct its reasoning without a live conversation to ask, and — increasingly — how much of the synchronization burden a system can carry automatically rather than leaving it to a human’s memory.

That third row is the one most likely to move over the next few years and the one worth watching closest. A spec that a human must remember to update is a spec that will eventually go stale, regardless of anyone’s intentions — that is a fact about human process, not about tooling. A spec that a system can partially regenerate or validate against the actual code, the way spec-kit’s convergence check compares implementation against plan or Tessl’s framework aspires to keep specs “as long-term memory, guiding agents as the app evolves,” changes the economics of the maintenance-cost side of this table considerably. As of 2026 that capability is closer to an early, unproven bet than a mature practice a team can rely on — worth tracking, not yet worth assuming.

The honest answer

This Library will not resolve the tension between living specs and static plans, because the field has not resolved it — the three tools examined here disagree with each other, and the most careful public analysis of them lands on skepticism about the heavier end of the spectrum rather than a clean recommendation. Picking a side to sound decisive would misstate how settled this is. The responsible position, for a team facing the checkout-spec moment this chapter opened with, is to name the tradeoff precisely enough to make the call on purpose: how volatile is this piece of the system, how many people or sessions will need its reasoning later, and how much of the sync burden can a system genuinely carry instead of a human’s memory. A team that answers those three questions deliberately, even briefly, has already done better than defaulting to whatever its spec tool happened to assume.