Keep documentation in sync with code using a scheduled agent

The code changes faster now. The README doesn't. Setup documentation goes stale one command at a time. Someone renames a script, moves a config file, or changes the required runtime. The application still builds for people who already have it installed. The next person following the README gets to discover the discrepancy.

A scheduled agent can look for those mismatches and prepare a small correction. Give it a defined part of the documentation and a way to verify what it proposes. An instruction to "improve the docs" produces a much harder review.

Choose one kind of drift

Start with installation instructions, a CLI example, or a small set of API examples. Each has a different source of truth. Package scripts can establish whether a command exists. A request schema can establish which fields an endpoint accepts. Neither establishes whether the surrounding explanation is useful to a new developer.

For a setup check, tell the agent to compare the README against the declared runtime, lockfile, environment example, and package scripts. Ask it to identify mismatches before editing. Keep broader rewriting out of the task so a reviewer can see which changes fix actual errors.

Suppose a guide still says to run test:unit, but the repository now uses a differently named script. A verified correction is useful. Rephrasing every paragraph around it makes that correction harder to find.

Give the agent a working environment

The check needs to run in an environment similar enough to exercise the documented commands. That means a setup script that installs dependencies, a run script that starts the app, the environment variables the commands expect, and written instructions for anything the agent can't infer. Configure those before expecting an unattended agent to validate a tutorial.

Use development services and test credentials. A command that requires production access should be flagged for a person to review. Don't supply broader credentials merely to make a documentation check turn green.

Be careful about what the environment proves. A command succeeding in an already prepared sandbox doesn't establish that the entire setup guide works on a clean machine. If the task is specifically to validate first-time installation, request a fresh test environment and inspect what preparation happened before the documented steps. Report the test conditions with the result.

Write the recurring prompt

For documentation maintenance, a weekly schedule is a reasonable starting choice. Use an explicit timezone for a cron schedule and check when the next run fires before you walk away from it.

If you don't want to host a scheduler and an environment for this, Hoplite automations run the prompt on a cron in a sandbox that can execute the commands your docs describe.

An example prompt:

Check the repository's setup guide for factual drift against the current scripts and configuration. Limit changes to installation and local-development instructions. Verify each changed command in the development sandbox and report its output and test conditions. Check for an existing PR addressing the same mismatch. Open a draft PR for confirmed corrections. Leave tone and unrelated sections unchanged. If a command needs unavailable services or credentials, report that gap instead of claiming it works. Do not publish documentation or merge the PR.

If the procedure becomes longer, put the checklist in the repository and tell the scheduled run when to load it. A checklist that lives only in someone's personal tooling won't be there when the job runs unattended.

Require evidence for each correction

The PR description should pair each correction with the fact that prompted it. A renamed command should cite the current script. An updated request example should show the check performed against the development endpoint or the relevant validation test.

Keep blocked checks separate from passed checks. An agent can confirm that an environment variable appears in configuration without proving that a third-party integration accepts its value. Those are different results, and reviewers need both stated plainly.

For command snippets, inspect quoting and working-directory assumptions. Documentation can be syntactically correct and still fail because it tells the reader to run a command from the wrong package directory.

Review the first scheduled run

Run the assignment once while you can watch it, with auto-merge disabled. Check whether it changed only the intended files, whether the tests exercised the edited examples, and whether any approval is pending. A schedule starts work; it doesn't remove the need for credentials, approvals, or review.

After merging the first correction, rerun the same assignment. A clean result should explain that it found no confirmed mismatch in the requested scope. If it invents more edits each week, narrow the instructions until leaving correct documentation alone is an acceptable outcome.