Why product specs go stale (and what keeps them current)

The spec lives where the product does not

Every decision that matters ends up in the repo. A pull request opens, someone argues with it, it merges. That sequence is the product changing shape. Anything outside the repo finds out later, if at all.

Look at what has to happen for the doc to keep up. A person interrupts the work they are doing. They switch applications. They find the right page among however many exist, remember what the old wording claimed, and write a correction that no reviewer will read. Every one of those steps is somewhere the task can get dropped, and under a deadline it gets dropped at the first one.

Teams tend to explain stale docs as a discipline failure. The same team keeps the code correct all day, because correcting the code is the work and because a reviewer catches them when they get it wrong. Neither of those forces reaches a page in another app.

Signals a doc has already drifted

Nothing announces the moment a document stops being true. It slides, and the first person to find out is usually the one who trusted it. A handful of checks surface the drift earlier than a confused new hire will:

• Compare the last-modified date against how often that area of the product ships. If the surface has shipped several times since anyone touched the doc, the doc describes an older product.
• Read the page with the shipped product open beside it. Field names, defaults, screenshots, and button copy go wrong before the concepts do.
• Check who owns it. When the named owner left the company or moved to another team, corrections stopped arriving a while ago.
• Watch chat. Engineers asking a question the doc already answers have either stopped trusting it or never found it, and both mean the doc is doing no work.
• Listen for settled trade-offs coming back up. The reasoning that would end the argument is usually sitting in a resolved review comment nobody can locate.

What a wrong spec costs

A new engineer reads the spec and builds a mental model of the system out of it. If that spec describes a design abandoned during review, the model is wrong in ways the person has no way to detect, and it goes straight into their first few changes.

Support and sales read the same page and end up describing the product as it was designed rather than as it shipped. Customers find that gap fast, usually in the worst context available.

Then the re-litigation. A trade-off the team already settled gets argued again from scratch, because the argument that resolved it lives in a comment thread on a merged pull request and nobody remembers which one.

Coding agents make a wrong sentence more expensive

Agents raise how much code a team ships, so the surface any given spec describes moves faster than it used to. The doc expires quicker for exactly the same amount of neglect.

There is a second problem. An agent that reads a stale sentence takes it at face value and builds against it. A human engineer would sense something was off and go ask in chat.

The same property pays off once the spec is in the repo, because agents read the repository as context. A spec sitting next to the code steers the code, and nobody has to paste it into a prompt for that to happen. A spec in a separate app is invisible to the agent entirely.

specgit's AI runs inside that same loop. Review posts inline comment threads on a draft, and Triage works through the comments that are open on it. Both run when a person invokes them, and every proposal waits for a human to approve it.

Move the doc to where the change happens

When the spec is a file in the repository that holds the code, the pull request changing the behavior can change the wording in the same commit. One reviewer sees both, and the review that already guards the code now guards the sentence describing it.

Engineering teams have done this for years and call it docs-as-code. It shut out the people who write most specs, since it asked a product manager to learn Git and Markdown before they could fix a sentence. specgit removes that requirement with a visual editor over the repo, which is the whole argument in docs-as-code for product managers and docs-as-code with non-technical contributors.

Set up the review gate correctly

Getting the doc into the repo does most of the work. Three settings make the difference between a folder people ignore and a folder that stays current:

• Path-scoped reviewers come from CODEOWNERS, which maps `docs/` to the people who should see changes there. Branch protection is set per branch and cannot target a folder by itself, so the two work together: CODEOWNERS assigns the reviewer, branch protection makes the approval required before a merge.
• Name an owner on the document rather than on the directory. Folder ownership diffuses until it means nobody, and a document with a named owner gets corrected when that person sees a change go by.
• Freshness is already on screen. The last commit date says when the page changed and blame says who wrote which line, so nobody has to maintain a review banner at the top of the file for the team to know how old a claim is.

What editing in the repo feels like

In specgit a save is a commit under your GitHub identity. An inline comment is a pull request review thread, so an engineer answering it from GitHub and a PM answering it from the editor are in the same conversation. Publishing is a merge. If the repo builds a documentation site, that merge ships the site, though specgit is not the thing rendering or hosting it. How it works walks through the mapping.

The tooling comparison is covered in Notion vs GitHub for product specs. The short version for staleness: a page in a general workspace can be beautifully organized and still describe a product that stopped existing in April, because nothing in the workspace has any relationship to the merge that changed it.

Start with one document

Migrating a wiki wholesale is a project nobody has time for, and most of what would move is already dead. Pick one spec for something still in development, since that is the document people read while it changes.

Export the Google Doc as Word and upload it. specgit converts it to Markdown in the repo through Microsoft MarkItDown, and from there the file behaves like every other file in the repository. Give it an owner, add the path to CODEOWNERS, and see whether the next change to that feature updates the wording in the same pull request.

The free plan covers one repository and five publishes a month, with unlimited collaborators and no card. Try it on a sample doc, or read the pricing if you want to know what happens after the first doc works.