Drift on merge
Live code paths compared to the docs that describe them.
Documentation drift detection
Catch documentation drift before the wiki goes quiet
Code merges without doc updates create drift. Moxie re-checks on every merge, flags gaps, and packages fixes into one weekly reviewable PR.
Quick Answer: To stop docs from going stale on GitHub merges, Moxie Docs automatically re-indexes your repository every time a pull request merges, compares the new code against existing documentation, and flags the drift. It then batches the fixes into a single reviewable docs-only Friday Cleanup PR, so your docs are corrected on the same cadence as your code without anyone rewriting them by hand.
- On every merge. Drift is caught while the change is still fresh.
- Visible gaps. Missing or stale pages show up in the workspace.
- Human review. Cleanup PRs are drafts - your team merges.
What you get
Built into the merge, not bolted on
Gap detection
See what is undocumented before onboarding or agents hit it.
Friday Cleanup
One scoped docs PR per week - review and merge when ready.
Severity-graded
Breaking changes flagged amber. Cosmetic churn is recorded but never becomes a PR.
Agents get the fix too
The corrected index serves Cursor, Claude Code, and Codex the same context over MCP.
Search still works
Jump from the index to source citations even when a page is stale.
How it works
The loop that keeps docs current
- 01
Connect GitHub
Install the app on the repos you want watched.
- 02
First index
Baseline docs and conventions from source.
- 03
Ship as usual
Every merge re-checks. Gaps accumulate in the workspace.
- 04
Friday Cleanup
Approve or edit the weekly docs PR.
The problem
Drift is a hundred small omissions
It is rarely one big event. A pull request renames a service, changes a default, or removes an endpoint, and the doc that describes it stays exactly as it was. Each gap is forgivable on its own. Together they are why nobody trusts the wiki — and why an agent reading those docs writes code against a system that no longer exists.
01 Renamed or moved modules
The architecture page still points at a path that moved three refactors ago.
02 Changed defaults and signatures
A function grew a required argument; the doc's example still calls it the old way.
03 Removed endpoints and flags
The API reference lists a route that now 404s, and an agent keeps recommending it.
04 Outdated setup steps
The onboarding guide's install sequence fails halfway through, so new hires debug it in Slack.
05 Conventions that moved on
AGENTS.md documents the old test runner, so the agent confidently runs the wrong command.
How detection works
Five signals, checked on every index
Moxie indexes the repository when you connect it, then re-checks the affected surface on every merge, comparing the current code against the docs that cite it. The detectors run in a fixed priority order, and each page carries at most one finding — the highest-priority one that fired — so you get a single clear signal, not a pile of overlapping warnings.
01 Stale content
A doc cites a source file whose change altered what the doc claims. The diff-backed signal, and the only one Moxie grades for severity.
02 Thin docs
A generated page has too little substance for the size of the subsystem it covers.
03 Undocumented API surface
A route handler or exported helper exists with no page describing it — the gap a new hire or an agent hits first.
04 Convention mismatch
A file diverges from a convention Moxie detected elsewhere in the same repo.
05 Orphaned pages
A doc references source paths that no longer exist while its own file is still in the tree.
Signal, not noise
Every finding is graded before it reaches you
Not every change that touches a documented file is worth a pull request. For stale-content findings, Moxie classifies the change and acts on the classification — and anything still too noisy for your team can be dismissed, muted for 7 or 30 days, or turned off per detector for the whole repo.
Breaking
Alters an API, signature, route shape, or behavior the doc explicitly describes. Queued for a fix.
Behavioral
A backward-compatible change such as a new field or an added branch. Flagged for review.
Cosmetic
Formatting, comments, internal renames. Recorded for reporting, but never opens a PR.
The output
What lands in the Friday Cleanup PR
On Pro and Team plans, the fixes Moxie is confident about arrive as one docs-only pull request each week — not a stream of separate PRs, and never an auto-merge. Between Cleanup PRs, every finding is already visible in the workspace and posted to the relevant GitHub pull request as an advisory check.
- Docs only. No source changes, so review is fast and low-risk.
- Cites its reasons. Each edit links the commit or code path that made the old text wrong.
- Yours to shape. Edit it, take part of it, or close it. Moxie opens pull requests; your team merges.
Advisory checks (Moxie Docs / Documentation) stay informational unless you require them in branch protection, where they become a hard merge gate.
At a glance
How teams keep up with drift
Process helps for a while, then loses to delivery pressure. Coupling the check to the merge is what holds.
Cadence
Quarterly doc days
Quarterly, if it survives crunch
PR doc checklist
Every PR, if the author remembers
Moxie
Every merge, automatically
Catches renames and deletions
Quarterly doc days
Only what someone happens to notice
PR doc checklist
The author's judgment on the day
Moxie
Checked against the source paths each doc cites
Reviewer effort
Quarterly doc days
A full rewrite sprint
PR doc checklist
An extra checkbox on every PR
Moxie
One scoped docs PR to approve
Keeps up with AI-written code
Quarterly doc days
No
PR doc checklist
Rarely
Moxie
Yes — re-checks on every merge
Serves agents current context
Quarterly doc days
No
PR doc checklist
No
Moxie
Same index, over MCP
| Quarterly doc days | PR doc checklist | Moxie | |
|---|---|---|---|
| Cadence | Quarterly, if it survives crunch | Every PR, if the author remembers | Every merge, automatically |
| Catches renames and deletions | Only what someone happens to notice | The author's judgment on the day | Checked against the source paths each doc cites |
| Reviewer effort | A full rewrite sprint | An extra checkbox on every PR | One scoped docs PR to approve |
| Keeps up with AI-written code | No | Rarely | Yes — re-checks on every merge |
| Serves agents current context | No | No | Same index, over MCP |
FAQ
Frequently asked questions
Get started
See the drift in your own repo
Connect a repository and the first index shows you what is already stale and undocumented. 14-day trial, no charge today.