Risk-Scored Ownership: A Gate for AI-Drafted Documentation

AI turns every developer into a documentation reviewer, yet nothing verifies that the reviewer reads the sections that matter. A risk-scored ownership rule gives the model the low-stakes paragraphs and reserves high-impact paragraphs for a human, without turning every sentence into a negotiation.

This post defines a two-score rule, a policy file, and a short Python gate that enforces the split on every pull request. The workflow assumes a free model access layer for drafting and a free server option for running the gate; MonkeyCode offers both. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The scores and policy file come from your documentation, not from the provider.

The reviewer's blind spot

When a model writes an entire page, your review inherits the model's emphasis; you check what the model is good at, not what your users depend on. A common DEV discussion noted that AI promoted every developer to reviewer, but nobody tested the reviewer. The practical fix is to determine ownership before the draft exists, not after you have read three versions.

Two scores, one rule

The rule uses two 1-to-5 scores per documentation file: harm (H) and coupling (C). Harm estimates what breaks if the section is wrong; coupling estimates how strongly that section binds to user code, data formats, or public endpoints.

Score	Harm example	Coupling example
1	Wording in an overview paragraph	Explains an internal helper
3	Wrong flag in one example	Names a public error message
5	Wrong default or removed API	Defines a REST route or persisted data shape

The ownership rule is deliberately binary: human if H >= 4 or C >= 4, and model otherwise. High harm belongs to a human because a wrong line can break user workflows; high coupling belongs to a human because it creates an external promise that the model cannot answer for. Everything between is still model-drafted, but you should spot-check it as part of a normal review.

Calibrate before you automate. Start with one document that caused a production incident and one page that nobody reads; assign the first a 5 on the axis that explains the break, and the second a 1 or 2 everywhere. Then review three more files and freeze those examples as team precedent.

An executable gate

The gate reads a plain-text policy file that maps each document to its two scores. A tiny Python script then derives the expected owner and compares it with an HTML comment at the top of the file. If the comment and the derived owner disagree, the gate returns a non-zero status and the merge stops.

# docs/ownership/policy.txt
# format: <relative-path> <harm> <coupling>
docs/api/compatibility.md 5 5
docs/api/overview.md 2 1
docs/guide/usage.md 3 2

#!/usr/bin/env python3
# ownership_gate.py - enforce risk-scored doc ownership.
# Usage: python ownership_gate.py policy.txt docs_root/
import re
import sys
from pathlib import Path

def expected_owner(harm: int, coupling: int) -> str:
    return 'human' if harm >= 4 or coupling >= 4 else 'model'

def read_owner(path: Path) -> str:
    text = path.read_text(errors='ignore')
    match = re.search(r'<!-- *owner *: *([A-Za-z0-9_]+) *-->', text)
    return match.group(1) if match else 'unset'

def main() -> int:
    policy_path, docs_root = Path(sys.argv[1]), Path(sys.argv[2])
    failures = 0
    for raw in policy_path.read_text().splitlines():
        line = raw.strip()
        if not line or line.startswith('#'):
            continue
        rel, harm, coupling = line.split()
        doc = docs_root / rel
        if not doc.exists():
            print(f'MISSING {rel}')
            failures += 1
            continue
        want = expected_owner(int(harm), int(coupling))
        got = read_owner(doc)
        ok = got == want
        status = 'ok' if ok else 'FAIL'
        print(f'{status} {rel} expected={want} got={got}')
        failures += not ok
    return 1 if failures else 0

if __name__ == '__main__':
    sys.exit(main())

The corresponding Markdown files need one comment each. A compatibility page is human-owned; an overview page can be model-owned.

## Compatibility

<!-- owner: human -->

The client uses the connection string from the first step.

# Overview

<!-- owner: model -->

This page describes the main request flow and the two primary endpoints.

Running the workflow

Follow five steps to make the gate part of your daily documentation loop.

1. Assign H and C for each file, then write the numbers into policy.txt.
2. Send only model-owned files to the free model access layer and instruct the model to add <!-- owner: model -->; keep the prompt small because free tiers are not infinite compute.
3. Write or rewrite human-owned files by hand, or verify every sentence before retagging them with <!-- owner: human -->.
4. Add the gate to CI with python3 ownership_gate.py docs/ownership/policy.txt .; the free server option runs it after each merge without consuming your main pipeline.
5. Treat a FAIL line as a merge-blocking comment, and investigate the reason before changing the tag.

The gate is intentionally simple. A binary rule cannot express uncertainty, and a file-level label cannot describe a split section, but both limits make the check predictable for contributors.

Reading a failed run

A commit that tags the compatibility page as model-owned produces a short and pointed CI log:

$ python3 ownership_gate.py docs/ownership/policy.txt .
ok   docs/api/overview.md expected=model got=model
FAIL docs/api/compatibility.md expected=human got=model

The relative path and the two labels give the author everything needed to reopen the page and change ownership after a real technical review. If you run the gate locally before pushing, paste the FAIL lines into the pull request and ask the author to prove ownership.

Where the gate remains blind

First, H and C are still subjective; a new team needs a calibration pass to align on what a 4 means in their domain. Second, file-level ownership hides mixed pages that combine a high-risk API table with safe narrative text. Third, the gate verifies the label, not the correctness of the labelled sentence, so a human still has to read model-owned files at a normal trust level.

Who should skip this

Small one-person projects without code review will find the labels adding one more ritual; the gate only adds value when another human must check the work. Teams that ship regulated or safety-critical documentation should not let a risk matrix decide ownership; compliance rules outrank any numeric heuristic. And if nobody on the team can review a human-owned section, the gate will fail without teaching anyone anything.

Start with three files in your policy, let the FAIL lines tell you what you actually expected the model to own, and adjust the thresholds from there. A two-score rule plus a trivial script cannot remove the human from the loop, but it moves the human from the whole document to the dangerous paragraphs.