In a repo worked on by AI coding agents, the docs have an unusual reader. Each new session starts cold, reads AGENTS.md, the design notes and the skills, and then builds on what it read. So a doc is not only for people: it is input to the next piece of code, and a wrong sentence in it becomes a wrong assumption in new work.
Yonto Player's repo has one rule for this, at the top of AGENTS.md: docs change in the same pull request as the code, never as a follow-up. This post is about the rule and the small habits around it.
The rule
The wording in the repo is short. docs/, AGENTS.md and skills/ are what the next session reads, so a change whose docs are not written is unfinished.
"Unfinished" is the useful word. A follow-up PR for docs is a promise that no build checks. If the docs are part of the definition of done, the reviewer sees the code and the prose it changes in one diff, and "did the docs change?" has an answer on the page.
The scope is deliberate. You update the docs that the change invalidates, and you find them by searching the subject across the whole repo. The aim is not to polish documentation, it is to keep it describing what the code does.
Name the sentence the change makes false
The PR skill in the repo (skills/open-a-pr) adds a step before you write the description. In my words: state in one sentence what this change makes false, then find every copy of that sentence.
The skill spells out the method:
- Search for the subject, not the wording. You cannot guess how someone else phrased a claim, so search for the thing the claim is about, using a few generic words for it, and read every hit.
- Read the file you edited first. It is the place you were already writing in, and the easiest to check.
- Change every copy. If a claim lived in two files, both change in the same PR, so the docs agree with each other.
- Check a correction the same way. The new sentence asserts something too, so search for its subject with the same care.
- Replace, don't append. Rewrite the old sentence instead of adding the right one beside it, so the page holds one answer.
Here is a simplified sketch of that step as a checklist, not the repo's exact text:
Before opening the PR 1. Write one sentence: "This change makes ___ false." 2. Pick the SUBJECT of that sentence (a feature, a name, a limit), not its wording. 3. grep -rn "<subject>" docs/ AGENTS.md skills/ README.md site/ <source dirs> 4. Read every hit. Start with the file you edited. 5. Update each copy in place. Then search for what your new text asserts. 6. Ask: is there a sentence anywhere this change contradicts? It is a habit made explicit, so an agent follows it the same way each time. Prose has no test suite of its own, so this search is the check.
Annotate a dated record, rewrite a live claim
The repo has two kinds of docs, and they are treated differently.
Live claims say how things are now: AGENTS.md, a docblock, the pages on the site. They are rewritten in place to say what is true today.
Dated records say what was decided and why, on a particular day. docs/design/ holds close to sixty of them, each named with its date. A record like that is history, and its value is that it still says what it said that day. So a later change adds a dated note to it and says what superseded the line, instead of editing the original.
A simplified sketch of the shape:
## Decisions (2026-10-24, #NNNN) - Feature X reads its limit from the server. ### Added 2026-10-29 (#MMMM) - Feature X also shows the limit on the settings page. The reader sees the original reasoning, then what was added and when. A live page that mentions the feature is rewritten to describe the current behaviour only.
Docs that a test or a build checks
Where a doc can be checked by a machine, it can be.
The developer guide on the site has a tutorial that walks through a small plugin. Its code blocks are copied from the plugin template in the CLI, and a test compares the page to the template, once for each language the page exists in. Change one without the other and the suite goes red.
The site build also checks pages. A page-metadata check fails the build when a page has no title or description, shares a title with another page, has an incomplete set of language alternates, is missing from the sitemap, or carries structured data that does not parse. It runs as part of npm run build, so for the properties the checks cover, a page that breaks them does not get as far as a deploy.
The principle is the same one as for code: if a property of the docs matters, write it down as something that can fail. What a build cannot check, such as whether a screen is called "Add source", is covered by the rule that the site's docs use the app's own words and change in the same PR as the strings.
The docs map
AGENTS.md is a briefing: the layout, the build line, the rules, and a table of "read this when" entries that point to the deep-dives in docs/agents/. Where it can, the repo keeps the detail in the deep-dive that owns it and points to it from the front page. Fewer copies of a claim means fewer sentences to search for when something changes, though some claims do live in more than one place, which is what the subject search is for.
What you can take from it
- Make docs part of "done", in the same PR as the code.
- Before you open the PR, name the one sentence the change makes false.
- Search for the subject, not the wording, and read every hit, starting with your own file.
- Rewrite live claims in place, and add dated notes to dated records.
- Where a doc can be checked by a test or a build, check it there.
- Prefer one home for each fact, and point to it from the others.
The next session then starts from something true.