Why product specs go stale when they live away from the code

A document's accuracy peaks the day you share it

Watch what happens to a spec written in a doc app. You share the link in chat. Engineers read it once, carefully even, then translate it into tickets and build from those. From that moment the ticket tracker is the working truth and the doc is a snapshot.

Then the product keeps moving. Scope gets cut in a standup. An edge case gets decided in a pull request comment. A vendor constraint forces a design change in week three. None of those decisions happen near the doc, and nothing carries them back into it.

Six months later the page describes a product that no longer exists, and the team quietly learns not to trust the docs folder. That is the part that costs money, because it takes the useful docs down with the rotten ones.

The mechanism is distance from the code path

Staleness tracks one variable: how far the document sits from the path a change travels. Code review is on that path, so an out of date code comment gets caught in the diff. A README in the same repo is close, so it gets caught sometimes. A page in another app is off the path entirely, and it only gets fixed when a person volunteers.

That is why the usual remedies underperform. A quarterly docs day fixes what someone remembers to look at. A checklist item in the ticket template gets skipped under deadline. Neither changes the distance, so both decay. Discipline is being asked to do a job that structure should be doing.

The same distance explains why the research that shaped a decision disappears from the spec, which we wrote about in the repo is meant for context, not just code.

How do you tell which docs are already stale?

You do not need a full audit to find the worst of it. A few signals do most of the work, and each one takes minutes per document.

Run this on the docs people actually open, not on everything. A page nobody reads can stay wrong for another quarter without hurting anyone.

• Compare last-modified dates against your release cadence. A doc covering an area that has shipped several times since the doc was last touched is wrong somewhere, and the behavior sections are where to look first.
• Read the page with the shipped product open beside it. Contradictions surface fast in field names, default settings, screenshots, and any sentence describing what a button does.
• Look for orphaned owners. If the person named at the top has moved teams or left the company, nobody is watching that page and its accuracy is now luck.
• Watch where questions get asked. When an engineer asks in chat something the doc already answers, they have stopped trusting it. That is the same signal arriving through a person.
• Check whether decisions are being re-argued. Settled trade-offs coming back up usually means the rationale never made it out of a resolved comment thread.

What stale documentation costs

The bill arrives late and lands on people who did not write the doc:

• New teammates onboard from it and build the wrong mental model of the product.
• Support and sales describe behavior as designed rather than as shipped.
• Settled decisions get re-litigated because the reasoning is buried where nobody can find it.
• Engineers route around the docs and ask in chat, so the definition work gets redone out loud, one question at a time.
• AI coding agents never see it. They work from the repository, so a spec in a doc app is not context for them at all.

The fix patterns that hold

Put the doc next to the code. Every change to the product passes through the repository. A document that lives there sits in the path of those changes instead of a browser tab away, so updating it is the same motion as changing the code, the same pull request can touch both, and the same review rules apply. This is the idea engineers call docs as code, and it excluded product people for years because the tooling assumed Git fluency. The longer version is in docs as code for product managers, and what changes for non-technical contributors covers the rest of the team.

Add a review gate. If a doc change needs an approval from the engineer who owns that area, wrong sentences get caught by someone who knows they are wrong. Branch protection already does this for code, and a doc in the repo inherits it, along with the CODEOWNERS rules that put the change in front of the right person without anyone deciding who to ask.

Name an owner per document, not per folder. Folder ownership means nobody owns anything. A name at the top of the page gives the reviewer someone to request, and it makes the orphan check above trivial when that person changes teams.

Show the freshness. A visible last-updated date lets a reader judge the page before acting on it, and it makes the gap between a doc and its release cadence obvious to anyone scanning a folder. It is a small change that turns silent rot into something you can see. A doc in the repo hands you this without a convention to maintain: the file carries the date of its last commit, and blame tells you which sentence changed then and who changed it.

Pick one document to start. Take whatever is in development right now, not the wiki. If it lives in Google Docs, export it as Word and specgit converts it to clean Markdown in your repo. Then let the next change to that feature update the doc in the same review as the code. That single habit is most of the fix, and it beats any migration plan.

Do AI agents make staleness better or worse?

Worse first. Agents raise how much code a team can ship in a week, and every shipped change is another chance for a document to become wrong. The assumptions in a doc expire faster than they used to, while the number of hours available to maintain it did not change. That pressure is the subject of when AI doubles the roadmap. Generated drafts add to it from the other end, because a draft is cheap to produce and just as expensive to keep true.

A stale doc is also more dangerous with agents in the loop than it was with only humans. A person reading a spec that contradicts the product notices and asks. An agent takes the sentence at face value and writes code against it, so the wrong answer arrives faster and with more of it.

The better half is that agents read the repository. A document kept in the repo becomes context an agent picks up without anyone exporting or wiring anything, which means keeping the doc current is now also how you steer the code. specgit's own AI works inside that loop: Review posts inline comment threads on the document like a human reviewer would, and Triage works through the open comments. It runs only when you invoke it, and every proposed change waits for a person to approve it.

You do not have to learn Git to do this

This is the gap specgit closes. You write in a visual editor in the browser, with no Markdown syntax and no Git commands. Saving is a commit attributed to you, with history you can walk back through. Highlighting a paragraph and commenting starts a real pull request thread engineers answer from GitHub. Publishing is a merge that honors the same required approvals your repo already enforces for code. How it works shows the mapping.

The doc ends up as a plain Markdown file in the repository, current for engineers, on the record for reviewers, and visible to every AI agent working there. If you are still deciding where the canonical copy belongs, Notion versus GitHub for product specs covers that choice, including the cases where Notion is the right answer.

You can open a Markdown file from any public GitHub repo in the editor at the try page, with no sign-up, if you want to see how the writing part feels before you move anything real.