Documentation has a shelf-life problem. The moment a spec is written as a plan — full of "will be" and "once implemented" — it starts aging. By the time the code ships, the document is already half-wrong. We wanted to fix that, so we redesigned how Intent generates and structures specifications from the ground up.
The Core Idea: Present Tense, Permanent Record
The shift sounds simple: write specs in the present tense, describing how the software works, not how it will work. But that small change has a big implication — a spec committed alongside code becomes a reliable reference, not an interim planning artifact that needs to be cleaned up later.
This is the principle driving Intent's updated approach to AI-generated specs. Every documentation spec now answers the question "what does this software do?" rather than "what are we about to change?"
Specs That Stay Current — Automatically
Present tense only holds value if the docs actually keep up with the code. That's where the other half of the system comes in.
With every new changeset, Intent's AI identifies which existing specs need updating. It does this via a semantic search over all current specs in the project — finding the ones most relevant to the change at hand. When an existing spec needs updating, a new version is created under the same lineage ID, preserving the full history while surfacing only the latest. When a PR is merged, that updated spec is committed to the branch and lands in main alongside the code.
This means you always have current documentation in your main branch — not as a separate documentation task, not as a follow-up ticket, but as a natural by-product of the normal delivery workflow.
That's a meaningful advantage over tools like OpenSpec, which lack this versioning mechanism. Intent's specs drift too — if you don't use Intent. But with it, the AI does the maintenance work, and the docs stay honest.
Two Artifact Types, Two Jobs
To make this work cleanly, we introduced two distinct artifact types:
-
Documentation specs — describe features and bug fixes in present tense. They cover intent, a plain-language summary, how the feature works, and scope (what's included and what isn't). For bugs, they document how the software now behaves correctly, but only when the fix touches something that was missing or misleading in existing documentation.
-
Architecture Decision Records (ADRs) — capture the why behind structural choices. ADRs are reserved for refactor changesets, where an architectural principle is being introduced or codified. They record the motivation, the correct approach, what not to do, and which repositories the decision applies to.
Decoupling artifact type from change type matters here. The kind of documentation you need isn't determined by whether something is a feature, bug, or refactor — it's determined by what you're trying to communicate and preserve.
Where They Live
Keeping these two artifact types separate extends to where they're stored in the repository:
- Documentation specs are committed to
.intent/specs/ - ADRs are committed to
.intent/rules/
This separation makes it easy to navigate — developers looking for behavioral documentation know where to look, and teams wanting to understand architectural constraints have their own canonical location. Intent handles routing specs to the right path automatically based on artifact type.
Raising the Bar for Documentation
Good documentation isn't just about coverage — it's about trust. Developers stop reading docs they've been burned by before. By making specs present-tense, purpose-built, AI-maintained, and committed at the right moment, the goal is documentation that earns that trust back.
The distinction between a spec that describes reality and one that describes intentions might seem subtle. But it's the difference between documentation that helps and documentation that misleads — and that difference compounds every time someone new joins the codebase.