When an AI writer starts opening branches with proposed doc updates, something subtle happens to the reviewer. The draft already exists, it reads well, and the diff is small. So you skim it, it looks fine, and you click merge.
That's the failure mode. A draft that reads well is not the same as a draft that's correct, and the whole point of putting a human in front of the merge button is to catch the gap between the two.
Read the claim, not the prose
Every doc change makes a claim about how the product behaves. "This endpoint returns a 404 when the resource is missing." "Auth tokens expire after 24 hours." The prose can be clean and the claim can still be wrong, because the agent inferred it from a code change instead of confirming it.
So when you review, separate the two. The writing being smooth tells you nothing about whether the claim is true. Find the sentence that asserts a behavior and ask whether you actually know that's the behavior. If you don't, that's the line to check, not the typos.
The three things worth checking every time
Most of a draft is safe to trust. A few parts aren't, and they're the same few parts almost every time:
- Auth and permissions. Agents are confident and frequently wrong about who can call what. If the draft touches authentication, verify it against the real flow.
- Edge cases and errors. The happy path is easy to get right. What happens on a bad input, an expired token, or a missing field is where drafts quietly invent behavior.
- Anything that changed versus anything that's new. A draft updating an existing page tends to be grounded. A draft introducing a brand-new concept is where the agent had the most room to guess.
If you only have two minutes, spend them there.
Make the cheap review the default
The reason rubber-stamping happens is friction. If reviewing means pulling the repo, reading the whole page, and reconstructing what changed, you won't do it carefully every time.
This is why the review lives in the branch. ReadMe's Reviews and Notifications put the proposed change in front of you as an isolated diff, with the context of what triggered it, so you can see exactly what the agent touched without rebuilding it in your head. A good agent helps here too: one that only proposes when it has something real to say keeps your review queue short enough that you actually read it. We wrote about that restraint in when an AI writer should and shouldn't propose a change.
How ReadMe puts this together
The GitHub AI Writer drafts the change and opens a branch. Branching, reviews, and notifications give you the workflow to check it before it ships, with Enterprise controls to require a review and restrict who can merge. The draft is the agent's job. The merge is still yours.
That division is the whole idea: let the machine do the writing it's good at, and keep a person on the one decision that actually carries risk. If you want to see it on your own docs, start a project or talk to us about Enterprise.
