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
The real power isn't just in how new specs are written. It's in what happens to existing ones.
Every time a new changeset is worked on, Intent's AI searches across all previously committed specs using semantic vector search to identify which ones are affected by the upcoming change. If a feature is being extended, the spec describing that feature gets a new version — same lineage, incremented version number. The updated file is committed to the branch alongside the code, so when the PR is merged, main gets both the change and the up-to-date documentation in one atomic step.
This is a meaningful advantage over approaches like OpenAPI specs, which are typically regenerated in isolation or left to drift between releases. With Intent, there's no separate documentation update step — the docs are part of the changeset, and the AI figures out what needs touching.
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.
ADRs and Scope
One intentional constraint worth calling out: when an ADR is created for a refactor changeset, it gets committed to all affected repositories in that changeset. If a decision only applies to a subset of repositories, it belongs in its own changeset. This keeps ADRs honest about their scope and prevents architectural decisions from quietly applying to codebases they were never meant to govern.
What This Means in Practice
The practical effect is that specs stop being things you have to maintain separately from the code. Because they're written in the present tense, updated by AI on every relevant changeset, and committed at merge time, they don't drift the way forward-looking planning docs do. A developer reading a spec three months later is reading documentation that was accurate at the last merge — no manual upkeep required.
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, kept current automatically, 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.