## Definition **Spec drift as a defect** is the framing that an outdated specification is not merely stale — it is an active defect category, worse than having no spec at all, because it confidently misleads both future readers and agents. ## Why drift is worse than absence A missing spec is a known unknown: the reader recognises the gap and proceeds with caution or asks. An outdated spec is a false positive: it presents itself as authoritative while describing a system that no longer exists. For a human reader this is annoying; for an agent acting on the spec as a prompt, it is a reliability failure. The agent generates code that is correct *with respect to the spec* and wrong with respect to the actual system. The module's Common Pitfalls section captures this directly: "a spec that doesn't change when the code changes is worse than no spec at all — it actively misleads future readers and agents." ## The defect category Framing drift as a defect — not as documentation decay — has practical consequences: - It belongs in the bug tracker, not the backlog. - It has a severity (proportional to blast radius of the divergent section). - It has an owner (whoever last modified the related code owns the spec update). - It blocks the next agent task that reads the spec, just as a broken test blocks CI. This is the logical complement of [[Living Documentation]]: if the executable spec is the truth, then an unexecuted, stale spec is a lie on record. ## Spec drift in the agentic context The problem is qualitatively sharper with agents than with human developers. A developer reading a stale spec may notice inconsistencies from surrounding context, code comments, or team knowledge. An agent following a stale spec-as-prompt has no such ambient knowledge; it treats the spec as ground truth, compounding the error into every file it touches. The [[Spec-as-Prompt Pattern]] makes the spec the canonical input to the agent. When that canonical input is wrong, the canonical output is wrong — at agent speed. ## Prevention - Treat spec updates as part of the definition of done for every code change. - Wire acceptance scenarios as CI gates ([[Continuous Validation]]); if they drift from the implementation, the build fails before the spec becomes the authoritative lie. - Never archive a spec change (e.g. via `/opsx:archive` in [[OpenSpec]]) without folding its delta back into the source-of-truth specs — the archive step is the mechanism that keeps the live spec current. ## Related - [[Living Documentation]] - [[Spec-Driven Development]] - [[Spec-as-Prompt Pattern]] - [[Continuous Validation]] - [[Three Amigos]] ## Sources - [[Modern AI Software Engineering - The Orchestrators Playbook]]