Docs API drift watch
Daily sweep of merged API changes → one rolling editor PR. Flags only; humans merge.
Daily clock diagram
Documentation rots at the speed of merges.
A repository ships code on a continuous timeline. Its documentation does not. The gap between the two is where confident onboarding goes to die and where the most expensive bugs — the ones caused by a reader trusting a doc — are seeded. — the operating principle of the watch
The watch is not a writer and it is not a linter. It is the alarm clock that tells an editor, every morning, exactly where the gap opened overnight.
From somewhere a doc is wrong to line 117 of this file.
The same merge, the same risk — reshaped from a vague editorial instinct into a citable worklist.
Before vs after panes
The editor opens their inbox
Twelve PRs merged overnight. Maybe one of them moved a symbol the docs name. Maybe not. The only way to know is to read everything.
- Doc drift surfaces during onboarding, when a new hire asks why the snippet doesn't run.
- Audits are episodic and large — "documentation week" once a quarter.
- The blast radius of a rename is invisible until it bites a reader.
- Editors triage on instinct because the signal is buried in the diff stream.
The editor opens one PR
The watch has done the diffing. The PR body is a per-document worklist with citations: changed path, changed symbol, the PR responsible, and the exact lines that still point to it.
- Drift surfaces on a daily cadence, before any reader trips on it.
- Audits are continuous — the worklist refreshes itself every morning.
- Renames carry their own follow-up; the old path is exactly what the docs still cite.
- Editors triage on evidence: file, line, PR, decision.
Every flag carries the receipt.
The PR body lists one section per stale document, with the exact line number and the PR that introduced the drift — the editor can move from inbox to fix without leaving the worklist. This format example uses live repository paths from the generated report shape.
Sample finding format
Conservative by design, complete by contract.
The watch is engineered so an editor can trust every flag and ignore every silence.
Three disciplines
Nothing is missed between runs.
The scan window starts at the created_at of the last
successful run — not "the last 24 hours". When an editor-review
PR is already open, the window stretches back to that PR's recorded
report window, so the flagging merges stay in scope.
Two signals, both engineered for low noise.
Path drift is exact and effectively false-positive-free.
Symbol drift chases only distinctive identifiers
— long enough, off the stopword list, snake- or camel-cased.
Generic names like build or parse never
reach the docs scan.
One rolling PR. Never a sibling.
The deliverable is a single PR on automation/docs-api-drift,
refreshed in place. An incomplete scan exits non-zero and leaves the
PR untouched — the next run rescans the same window rather than
advancing past drift that was never published.
The walkthrough explains every cell of the worklist.
Six steps, two signals, the failure-mode atlas, the editor contract, and the tunables — all on one long-form page. The Markdown is the source of truth for the editor's role.