How to Describe Code Changes Without Rewriting the Spec Every Time

Specs go stale because updating them is painful: you change one behavior, the spec for it sits in a long markdown file, and rewriting half of it costs more than the change. Six months later the spec contradicts the code, the next developer trusts the spec, and ships a bug. The fix is not discipline; it is a spec format that describes changes without rewriting.

What a delta is

A delta is a document with three sections. ADDED: new behavior, appended to the main spec at archive. MODIFIED: changing behavior, replacing the old requirement at archive. REMOVED: deprecated behavior, deleted at archive. You never rewrite the main spec during a change; you write the delta, and archive applies it mechanically.

A concrete example

Adding two-factor auth to an existing login. ADDED: the system MUST support TOTP-based two-factor, with enrollment and login challenge scenarios. MODIFIED: session timeout drops from thirty minutes to fifteen, replacing the old requirement. REMOVED: Remember Me is deprecated in favor of 2FA. The main spec stays untouched until archive, then absorbs the changes.

Why deltas beat rewrites

The diff is the document, so reviewers see exactly what changes instead of mentally diffing a rewrite. Two changes can touch the same spec file without conflicting, since each lives in its own delta folder and archives independently. Review scales with the change, not the spec size. And modification becomes first-class, which fits brownfield work where most development modifies existing behavior.

Spec behavior, not implementation

Good spec content: inputs, outputs, error conditions, external constraints, things observable from outside. Bad spec content: class names, library choices, step-by-step plans; those belong in design. The quick test: if the implementation can change without changing what outsiders see, the change does not belong in the spec. React Context versus Redux is design; "the system SHALL allow theme switching" is spec.

The trade-off

Do not delta everything. Brand-new features need new spec files, not deltas; a delta with nothing to modify is awkward, and a modification written as a new spec creates two competing authorities. For a solo throwaway project, direct spec edits are cheaper. Deltas earn their keep on code that lives long enough for spec and code to drift, which is most production code.

The smallest test

Take your next change and write it as a delta with the three sections. If it reads cleanly, the format fits; if you want a full rewrite instead, the change is bigger than a delta.