Sign the Sentences, Not the PR: An Approval Ledger for Model-Drafted Doc Blocks
Most documentation reviews approve a pull request, not a sentence. That is the failure mode worth fixing first, because a single approval granted in October can silently keep covering paragraphs a model rewrote in December. The workflow below binds every human signature to a hash of the exact text it approved, so re-approval becomes a mechanical consequence of editing rather than a matter of…
Documentation reviews typically approve pull requests, not individual sentences. This issue can be addressed by assigning a unique hash to each human signature that approves a specific text block. The workflow involves creating a Python checker that runs in pre-commit and CI to verify whether a named human has signed the exact text of a block.
The approval record lives in review history while the file is continuously updated, which can lead to signatures becoming disconnected from their original content. By linking both hash and approval records, you ensure that both the input content and human accountability are verifiable.
Before implementing any tooling, it is essential to define the ownership boundaries for each unit of content. Each block should be marked with an HTML comment pair, indicating the type of block (model or human) and the owner. Blocks marked as owner=human do not undergo the approval process, allowing for flexibility and explicit escape hatches.
Blocks marked as owner=model require a signature, and any changes to these blocks invalidate the existing signature. The final drafting process should restrict modifications to only those blocks designated as owner=model, with no introduction of new numbers, dates, or versions.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
