AI Writes, You Verify: A Documentation Review Pipeline for Skeptics

Last week I deleted a function that had been "documented" by a comment explaining a behavior the function hadn't had in three versions. The comment was confident. The function was gone. This is the real failure mode of AI-generated docs: they can be fluent, plausible, and wrong. Not because the model is bad, but because no human verified what the text claims. The fix isn't to avoid AI. It's to build a checkpoint where the model drafts and the human signs off. The Ownership Split A model can summarize code, describe parameters, and turn commit messages into release notes. It cannot know why a decision was made, which edge cases are career-ending, or which comments are now dangerous. My rule of thumb: The model drafts: API descriptions, usage examples, parameter tables, changelog bullets from git history. A human owns: security implications, business rules, architectural trade-offs, deprecation warnings, anything tied to customer promises. The pipeline below makes that split explicit. It generates a draft, then forces a review issue with a checklist that separates the two categories. The Pipeline I run this as a GitHub Actions workflow on every merged PR that touches src/ . It takes the diff, sends it to a language model with a strict output schema, and opens a documentation review issue. Here's a condensed version of the workflow YAML: name : docs-draft on : pull_request : types : [ closed ] branches : [ main ] jobs : draft : runs-on : ubuntu-latest steps : - uses : actions/checkout@v4 with : fetch-depth : 0 - name : Generate doc draft env : API_BASE : ${{ secrets.MONKEYCODE_API_BASE }} API_KEY : ${{ secrets.MONKEYCODE_API_KEY }} run : | git diff origin/main HEAD -- src/ > diff.txt python draft_docs.py diff.txt - name : Open review issue uses : actions/github-script@v7 with : script : | const body = require('fs').readFileSync('review_body.md', 'utf8') await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: `Docs review: ${context.