How to prevent documentation drift

Documentation fails quietly. splitshift-api renames a request field; splitshift-docs keeps the old name. The next reader sends a field the API no longer accepts.

Run a maintenance agent on a schedule. It reads the code and docs together, then opens a pull request only when the code disproves a documented claim.

Commit this as agents/documentation-maintainer.yaml in splitshift-docs:

ellipsis:
  version: v1
  name: Documentation maintainer
  description: Opens a pull request when documentation drifts from the code

claude:
  system: |
    Keep splitshift-docs accurate to splitshift-api.

    Read the API reference and configuration docs in splitshift-docs.
    Verify every concrete claim against the current splitshift-api code:
    endpoint paths, request and response fields, configuration names,
    defaults, environment variables, and setup commands.

    Change only claims the code disproves. Do not restructure pages, add
    tutorials, or rewrite accurate prose. If nothing has drifted, make no
    changes and say so.

    When you find drift, make the smallest accurate edits in
    splitshift-docs. Run its existing documentation checks, then open one
    pull request. In the pull request body, name the code file that proves
    each edit. Do not change splitshift-api.

trigger:
  type: cron
  schedule: "0 9 * * 1"

sandbox:
  repositories:
    - name: splitshift-api
    - name: splitshift-docs
  github:
    permissions:
      contents: write
      pull_requests: write
    repositories: [splitshift-docs]

budget:
  session: 2.00
  week: 8.00

Three parts do the work. The trigger starts a fresh session every Monday at 09:00 UTC. Both repositories are cloned into the sandbox, so the agent can compare them directly. The runtime GitHub token can write only to splitshift-docs.

When splitshift-api#437 renames a request field and adds a required setting, the agent opens one pull request:

Updates 2 pages for the shift-trade API changes in
splitshift-api#437.

- docs/reference/shift-trades.mdx: the claim request now uses
  `worker_id`, not `user_id`.
- docs/reference/configuration.mdx: add the required
  `TRADE_EXPIRY_SECONDS` setting.

Evidence:
- splitshift-api/src/routes/trades.py
- splitshift-api/src/settings.py

Left alone: docs/guides/trading-shifts.mdx describes the user flow,
which #437 did not change.

Write to one repository

The agent needs both repositories on disk, but it should write to only one. Scope the runtime token to the docs repository:

sandbox:
  github:
    permissions:
      contents: write
      pull_requests: write
    repositories: [splitshift-docs]

Ellipsis clones both sandbox repositories with a separate clone token. The token available to git and gh inside the running session is restricted to splitshift-docs, so the agent can read the API code without pushing to it.

Ask for evidence, not a rewrite

Start with API references and configuration pages. Their claims map to routes, schemas, settings, and commands in the repository. Conceptual guides require more editorial judgment and make it harder to distinguish maintenance from a rewrite.

Name the facts the agent should inspect, require a code reference for every edit, and define the empty case. A prompt that says only "keep the docs current" leaves the scope, standard of proof, and stopping condition undefined.

Compare the current repositories

Each scheduled run starts from the current code and documentation. The agent does not need to remember its previous session or infer what changed since then. If a run is skipped, the next comparison can still find the mismatch.

The pull request keeps the review human. The agent finds and writes the diff; a person decides whether the cited code supports it.

Next

Change the cadence with How to automate your daily standup, or review every config field in the agent config reference.