Clarity Gate
The Clarity Gate is a quality test for a spec built around a single question: can a different agent, or a new session of the same agent, generate functionally equivalent code by reading only the spec? If not, the spec contains implicit assumptions, and those assumptions are the main cause of spec drift: when the spec says one thing and the code has evolved into something else.
Writing a good spec is half the challenge; the other half is keeping it aligned with the code as the project progresses. Drift happens fast: all it takes is a minor decision by the agent that the spec didn't cover, or an adjustment during implementation that nobody carried over to the document. A drifted spec is an active risk, because whoever consults it makes decisions based on incorrect information.
The Clarity Gate as a Test and as a Diagnostic
It is a test any team can apply: give the spec to another agent with no context and compare the results. Whatever the second agent does differently is what the spec didn't say—knowledge that lived in the original conversation and never got written down. It also serves as a cleaner diagnostic than traditional debugging: if the spec is correct and the code doesn't comply with it, the problem lies in the implementation and the task is regenerated; if the spec is wrong, the spec is corrected and the code regenerated.
The three levels of a spec's life
Böckeler's taxonomy describes how different teams manage the life cycle:
- Spec first (spec-first). It is written before coding, guides the current task, and is then discarded. Drift is not a problem, but the documentation is lost as an asset.
- Anchored spec (spec-anchored). It is maintained as living documentation of the system: when the code changes, the spec is updated. Drift is a real risk that demands discipline. This is where most teams work today.
- Spec as source (spec-as-source). The spec is the primary artifact: only the spec is edited, and the code is regenerated. Drift disappears by design, but this approach is still experimental.
Strategies for Keeping Specs Alive
For teams working with anchored specs, four practices have become established:
- Update the spec in the same commit as the change, because "later" never comes.
- Version it, with a history of what changed and why.
- Review the status of specs in the retrospective, to decide which ones are still alive.
- For critical specs, create conformance tests that verify the code complies with the spec.
The Current-Truth and Change-Proposal Pattern
To these is added a simple pattern, popularized by OpenSpec, that separates what is current truth from what is only a change proposal. The system's specs live in one directory; change proposals, in another. When a change is completed, its spec is merged into the current one and the proposal is archived. The pattern is not tool-dependent: any team can adopt it with two folders and a rule, and it resolves the most common confusion: not knowing whether what you are reading describes what exists or what was intended.
Common mistake
"I'll update it later." Later never comes: the spec is updated in the same commit as the change, or it drifts. Just as harmful is assuming a spec is clear without testing it (the Clarity Gate reveals implicit assumptions that can't be seen from inside the original conversation) and mixing what is current and what is proposed in the same place, because readers can't tell whether it describes what exists or what was intended, and neither can the agent.
Resources
📊 Guía didáctica SDD [SDD Teaching Guide, in Spanish]Resources · Scrum Manager
🏦 SDD en equipos ágiles [SDD in Agile Teams, in Spanish]Skill Arena · Scrum Manager
References
- Böckeler, Birgitta. (2025). "Understanding Spec-Driven Development." Thoughtworks / martinfowler.com.
- OpenSpec (project documentation).
See also
Want to advance in agility? You can search for course and exam calls or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.