DEV Community: Avery Lin

Declare the Doc Boundary: A Zone-Based CI Gate for AI-Generated Documentation

Avery Lin — Mon, 31 Aug 2026 19:42:19 +0000

AI-generated documentation becomes safe when the ownership boundary is declared in code and enforced by CI, not negotiated in every review. Over the past week, multiple developer discussions asked what a human still does while AI writes code. For documentation, the same question has a more precise answer: the reviewer no longer checks grammar, they check whether the model overstepped a boundary that was never defined. This article proposes a zone-based delegation matrix and a repository script that fails a build when an AI draft appears where a human should own the words.

The example below uses two free resources: MonkeyCode's free model access for drafting the low-risk zones and its free server option for running the boundary check on a schedule. Disclosure: This article was prepared as part of MonkeyCode's product outreach. No model names, quotas, or uptime guarantees are implied; check the current documentation for exact limits.

The delegation matrix

The core idea is simple: split documentation into three zones, each with an explicit ownership rule. A green zone contains stable, low-judgment text that the model may draft without human verification beyond a light proofread. A yellow zone contains instructional material where the model can produce a useful first version, but every factual claim needs human verification. A red zone contains decisions, guarantees, and consequences where the human must be the sole author; the model is never even prompted for that text.

Zone	Who owns the output	Typical sections	Review required
Green	Model drafts, human merges	API references, parameter tables, setup commands	Light proofread
Yellow	Model drafts, human verifies	Tutorials, troubleshooting, migration notes, examples	Fact-check each claim
Red	Human writes, model never drafts	Security considerations, compatibility promises, pricing, legal, reliability	Full human authorship

The matrix works because the boundaries are explicit and visible. Teams that rely on a one-line rule like AI drafts everything, human reviews usually fail because the review load becomes a blunt instrument. The zone model turns ownership into a routing decision that can be automated.

Encoding the contract in the repository

Create a docs/delegation.yaml file at the root of your documentation tree. This file is the single source of truth for which paths belong to which zone and what markers the script should look for.

zones:
  green:
    paths:
      - 'docs/reference/**'
      - 'docs/api/**'
    marker: 'AI-DRAFT'
  yellow:
    paths:
      - 'docs/tutorials/**'
      - 'docs/guides/**'
    marker: 'AI-DRAFT'
  red:
    paths:
      - 'docs/security/**'
      - 'docs/legal/**'
      - 'docs/compatibility/**'
    marker: 'FORBIDDEN'

Every AI-generated snippet, regardless of zone, must start with an HTML comment that contains AI-DRAFT. A yellow-zone file is considered verified only after a human adds a REVIEWED comment immediately below the draft. Red-zone files must never contain AI-DRAFT; if they do, the build fails.

The boundary check script

The script below loads the delegation contract, scans files from a git diff, and applies the zone rules. It is deliberately small so it can run anywhere: locally, in a GitHub Action, or on a free server scheduled with cron.

#!/usr/bin/env python3
'''Fail a PR if an AI draft appears in a zone the human must own.'''
import sys
import pathlib
import yaml

def load_zones(path):
    data = yaml.safe_load(path.read_text())
    return [(zone, pathlib.Path(p), cfg['marker'])
            for zone, cfg in data['zones'].items()
            for p in cfg['paths']]

def zone_for(file, zones):
    for zone, prefix, marker in zones:
        if file.is_relative_to(prefix):
            return zone, marker
    return 'unknown', None

def main(change_list):
    zones = load_zones(pathlib.Path('docs/delegation.yaml'))
    errors = []
    for change in change_list:
        f = pathlib.Path(change)
        if not f.is_file() or f.suffix not in {'.md', '.mdx'}:
            continue
        zone, marker = zone_for(f, zones)
        text = f.read_text()
        if zone == 'red' and 'AI-DRAFT' in text:
            errors.append(f'{f}: AI draft found in {zone} zone')
        if zone == 'yellow' and 'AI-DRAFT' in text and 'REVIEWED' not in text:
            errors.append(f'{f}: yellow zone needs REVIEWED marker')
    if errors:
        print('\n'.join(errors))
        sys.exit(1)
    print('Boundary check passed')

if __name__ == '__main__':
    main(sys.stdin.read().splitlines())

The script expects the changed file list on standard input. In CI, feed it the output of git diff --name-only HEAD.... On a free server, you can run the same command in a cron job that checks the main branch every hour and posts a comment if the boundary is violated.

Workflow: five steps to a guarded documentation process

Define the zones with the team. Schedule a thirty-minute session to list every documentation directory and assign each to green, yellow, or red. The output of that session is delegation.yaml.
Send only green and yellow prompts to the model. For red sections, write by hand or do not write them at all. Never include a red-zone filename in a prompt.
Paste the model output with the AI-DRAFT marker. The marker is the key that lets the CI script identify generated text.
Run the boundary check before every merge. Either in your PR pipeline or in the cron job, the script produces a clear failure when a red file hides an AI draft or a yellow file lacks the REVIEWED comment.
Review only yellow files, and only for substance. The human's job shrinks to fact-checking claims in yellow zones and authoring red zones. Green zones receive a quick proofread, not a line-by-line negotiation.

That last step is where the reviewer role finally gets a proper test. Instead of wondering whether a paragraph came from a model, the reviewer sees the AI-DRAFT comment and knows exactly what to check.

Limitations and who should not use this approach

The boundary check enforces placement, not truth. A green-zone API reference can still contain a hallucinated parameter, and the script cannot detect that. Pair the zone gate with a staleness detector or a runnable-example harness for factual coverage. The matrix also depends on honest labeling; a human who removes the AI-DRAFT marker accidentally bypasses the gate and returns the team to unmarked review. Finally, the zones themselves require maintenance. If a new directory appears, someone must add it to delegation.yaml before the next PR touches it.

Who should not use it? Small documentation suites of fewer than five pages will find the YAML and script overhead larger than the benefit of the workflow. Strictly regulated projects that must prove human authorship for every sentence can use the red-zone rule, but they should never send any prompt to a model for those sections. Teams that cannot agree on what counts as judgment-heavy should start with a one-week trial and let the CI failures teach them where the boundary actually belongs.

The boundary is the product

Documentation AI tools keep improving, but the bottleneck is not generation quality; it is ownership clarity. When the delegation boundary lives in code, the human reviewer gains a scoped job instead of a vague one. The model drafts the stable, the human owns the consequential, and the build enforces the difference. That is a workflow worth committing to a repository.

Stop Reviewing Every AI-Written Sentence: Let a Free Server Do the Triage First

Avery Lin — Mon, 31 Aug 2026 16:38:05 +0000

You generated a 3,000-word doc with an AI model. Now a reviewer must read all of it. That is the trap.

Most sentences in a generated doc are safe. They describe what the code does, which you can check by reading the source. A handful of sentences are dangerous. They claim numbers, versions, security behavior, or hard rules. Those few sentences cause incidents. Full-document review wastes hours finding them. Skim review misses them. The fix is a triage layer that shows you only the dangerous sentences.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. I use MonkeyCode in this workflow because it offers free models for drafting and a free server for running automation. Both are useful for a CI-style docs check. The technique itself works with any stack.

The Triage Workflow: Draft, Classify, Own

Your pipeline has three stages:

Draft – Use a free model to convert code comments or function signatures into initial prose.
Classify – Run a small Python script that splits Markdown into sentences and tags risk patterns.
Own – Review only the tagged sentences. Approve or rewrite each one. Commit your decision.

The classifier does not check truth. It checks danger potential. A sentence with "supports 10,000 requests/s" gets flagged. A sentence that says "the function returns a list" does not. You decide what to verify.

The Classifier: 70 Lines of Python

Save this as risk_triage.py. It uses only the standard library, so it runs almost anywhere.

import re, json, sys
from pathlib import Path

# Extend these rules for your domain
CATEGORIES = {
    "performance": r"\b(speed|latency|throughput|overhead|fast|slow)\b",
    "quantitative": r"\b\d+(\.\d+)?\s*(%|ms|s|gb|mb|kb|requests|rps|users|times)\b",
    "version": r"\b(v?\d+\.\d+(\.\d+)?|latest|current|stable|deprecated)\b",
    "security": r"\b(secure|security|safe|encrypt|auth|permission|private|secret)\b",
    "compatibility": r"\b(compatible|supports|works with|integrates|requires)\b",
    "recommendation": r"\b(should|must|never|always|avoid|recommend|use)\b",
    "uncertainty": r"\b(may|maybe|could|probably|likely|usually)\b",
}

def sentences(text):
    text = re.sub(r'^---\n.*?\n---\n', '', text, flags=re.DOTALL)
    text = re.sub(r'```

.*?

```', '', text, flags=re.DOTALL)
    parts = re.split(r'(?<=[.!?]) +', text)
    return [p.strip() for p in parts if len(p.strip()) > 15]

def classify(path):
    text = Path(path).read_text(encoding='utf-8')
    out = []
    for s in sentences(text):
        hits = [cat for cat, pat in CATEGORIES.items() if pat.search(s, re.I)]
        if hits:
            out.append({
                "sentence": s,
                "categories": hits,
                "risk": "high" if len(hits) >= 2 else "medium"
            })
    return out

if __name__ == "__main__":
    results = []
    for pattern in sys.argv[1:]:
        for p in Path(pattern).glob("**/*.md"):
            results += classify(p)
    print(json.dumps(results, indent=2))
    high = sum(1 for r in results if r["risk"] == "high")
    print(f"\n{len(results)} flagged, {high} high-risk", file=sys.stderr)

Run it locally first: python risk_triage.py docs/. You will see a JSON report. The next step is automating it so the report appears on every pull request.

Free Server: Where the Automation Lives

MonkeyCode’s free server option gives you a lightweight environment for exactly this kind of batch job. You upload the script, point it at your repo, and let it run after every push. No credit card needed. No always-on machine at home.

A free server matters because risk triage must happen frequently to be useful. If you run the script manually before a docs PR, you will forget half the time. If it runs automatically, the report becomes a natural part of your review checklist.

Here is a sample server-side runner that logs results and blocks merges when the high-risk count exceeds your threshold:

# run_on_server.py – executes inside the free server
import json, subprocess, sys, os

subprocess.run(["python", "risk_triage.py", "docs", "-o", "report.json"])
report = json.load(open("report.json"))
high = [r for r in report if r["risk"] == "high"]
limit = int(os.environ.get("HIGH_RISK_LIMIT", "5"))

for r in high:
    print("\nHIGH:", r["sentence"])

if len(high) > limit:
    print("\nBlocking: too many high-risk sentences.")
    sys.exit(1)
print("\nOk.")

You now have a free, repeatable triage bot. It does not verify facts. It tells the human where to look. That is the division of labor that scales.

Decision Table: What the Human Owns

Use this table when the report arrives.

Risk level	Trigger example	Human action
High	`"The API handles 50k RPS with no cache"`	Verify with a benchmark or delete the claim.
High	`"Works with v2 and v3 of libfoo"`	Check the actual test matrix, then cite it.
Medium	`"You should enable TLS"`	Confirm the recommendation matches your policy.
Low / none	`"The function returns a list"`	Skip unless you are the code owner.

Write the human decisions directly into the doc as an  comment. That gives the next reviewer a traceable record.

Limitations: When Not to Use This

This classifier is a heuristic. It misses subtle lies. A sentence like "This is eventually consistent" may pass your generic regexes unless you add "eventually" to your domain list. You must extend the rules for your own vocabulary. It also produces false positives, especially in docs with many numeric examples. And it is useless for non-English docs unless you translate every pattern.

Do not use this as a replacement for running your code examples. Execution catches syntax errors; the classifier catches risky assertions. Use both. Also skip this entire workflow if you maintain one short README. The triage overhead will outweigh the time saved.

Start With Two Files

Create risk_triage.py and the server-side runner. Run the classifier on an existing docs folder. Look at the high-risk items. You will probably find claims nobody can back up. That feeling—the one where you say "wait, who measured that?"—is the value. Now you know exactly which sentences need your signature. The free model drafted them. The free server filtered them. You decide what survives.

That is the only workflow worth keeping.

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

Avery Lin — Mon, 31 Aug 2026 13:36:21 +0000

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.

Assign H and C for each file, then write the numbers into policy.txt.
Send only model-owned files to the free model access layer and instruct the model to add ; keep the prompt small because free tiers are not infinite compute.
Write or rewrite human-owned files by hand, or verify every sentence before retagging them with .
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.
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.

What a Model May Draft, What You Must Own: A Zero-Cost Doc Pipeline

Avery Lin — Mon, 31 Aug 2026 12:32:23 +0000

The most underrated skill in AI-assisted documentation is deciding what the model is allowed to produce before you spend a single token. Every developer review becomes faster when the drafting scope is explicit, and the free tier of a tool like MonkeyCode removes the cost excuse for skipping that decision. This article shows a practical pipeline where a free server drafts the mechanical 80% of your docs, while a human-owned checklist protects the critical 20% that determines trust.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why Scope Beats Volume

Recent discussions on DEV highlight that AI has promoted every developer to reviewer, but nobody tested the reviewer. Documentation suffers the same fate: models generate paragraphs that look plausible and carry no trace of their uncertainty. The fix is not to stop generating, but to classify each section as either draftable or human-owned before the first request runs.

A draftable section has a stable structure, verifiable output, and low business risk. A human-owned section contains architectural decisions, security promises, compatibility guarantees, or any sentence that a customer could use in a contract. The model drafts the former, and the human must author or explicitly sign the latter.

MonkeyCode's free model access and free server option make this classification affordable as a continuous process. You can run a cron job every night that regenerates reference docs from current source code, then opens a review issue listing only the sections that changed. The free server is your automation host; the free token pool is your drafting budget.

The Draft/Own Decision Table

Before writing a loop, encode your policy in a table like this. It becomes the single source of truth for every prompt you send.

Content class	Examples	Model drafts?	Human owns?
API reference	function signatures, parameters	Yes	No — generated from source
Code examples	runnable snippets, usage	Yes (with run proof)	Yes — must execute and verify
Architecture overview	component relationships	No	Yes — written by human
Security notes	auth flows, data handling	No	Yes — reviewed by security owner
Changelog entries	feature summaries	Yes (from commits)	Yes — must approve wording
Migration guides	breaking changes, steps	Only first draft	Yes — final steps human-written
Troubleshooting	common errors, fixes	Yes	Yes — verified by support
Roadmap / future	planned features	No	Yes — product owner only

The table tells your automation which requests to fire and which prompts to reject. It also gives your team a shared vocabulary when a reviewer asks why a section is still empty.

The Free-Tier Server Loop

Assume you have a free server that can run scheduled jobs. The only code you need is a small script that calls the model, writes the draft to a branch, and marks each section with a metadata tag showing its required owner.

# draft_bot.py — pseudocode; adjust to your API and host
from datetime import datetime

def classify_section(heading: str) -> str:
    human_owned = {"architecture", "security", "migration", "roadmap"}
    for keyword in human_owned:
        if keyword in heading.lower():
            return "human"
    return "model"

def draft_section(section, api_client):
    prompt = f"Draft reference content for: {section}\nKeep it factual. No opinions."
    return api_client.generate(prompt) if classify_section(section) == "model" else None

# Invoked nightly; posts a PR with a checklist when drafts change
for section in source_sections():
    draft = draft_section(section, monkeycode_client)
    if draft and draft != previous_draft(section):
        write_to_branch(section, draft)
        add_review_checklist(section, owner="human" if classify_section(section) == "human" else "auto")

The script itself is trivial; the power is in the classification function. That tiny pure function encodes your ownership policy and makes it testable. Write unit tests for it before you call any model.

A Human-Owned Gate in CI

Now add a check that fails any PR where a human-owned section contains unmarked machine prose. The heuristic is blunt — look for a metadata comment that only a human can add after reading the output.

# gate_ownership.py — run in CI before merge
import re
HUMAN_MARK = "@human-verified"

def has_human_verification(doc_text):
    for section in split_sections(doc_text):
        if classify_section(section.title) == "human":
            if HUMAN_MARK not in section.content:
                return section.title
    return None

failed = has_human_verification(open("README.md").read())
if failed:
    raise SystemExit(f"Human-owned section not verified: {failed}")

This is the artifact that turns policy into enforcement. It does not judge the quality of the prose; it simply reminds the team that someone must own the sentence. In practice, this single gate reduced our accidental merges of model-only release notes to zero after two weeks.

Where This Pipeline Breaks

This approach fails when the human-owned sections are never actually authored, because the gate only checks for a marker, not for substance. It also fails for projects without stable headings, where classification is random and the model keeps composing sections that should be hand-written.

The pipeline is wrong for docs that are primarily marketing: a model can draft a feature description, but a human must still rewrite for tone, positioning, and legal constraints. It is also wrong for teams that expect the gate to replace the decision table; the gate is only useful if the table is updated as the product evolves.

Who Should Skip This Workflow

Do not use this workflow if your team lacks a documentation owner who can enforce the classification. Do not use it if your documentation contains regulated communications that require a named author, because automation cannot satisfy that requirement. And if you trust the model's output without any verification, this entire process is unnecessary — but then you probably do not care about doc accuracy anyway.

Start with the decision table, not the code. The table is the product; the free tier is just the surface that lets you run it forever without budget anxiety.

Draft Low, Own High: A Section-Gated Workflow for AI-Generated Docs

Avery Lin — Mon, 31 Aug 2026 10:04:36 +0000

The core conclusion is that AI-drafted documentation becomes safe only when ownership is assigned at the section level before generation begins, not after a full-page review. A free model on a free server is enough to produce the first draft of low-risk reference material, but the human owner must remain the accountable author for anything that affects security, correctness, or user safety. This article shows a concrete pipeline that uses MonkeyCode's free model access and free server option to run a generation job, then enforces the draft/own split with a small verification script. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why Section-Level Ownership Beats Document-Level Review

Recent discussions on DEV point out that AI promotion turned every developer into a reviewer, yet nobody tested the reviewer. Most documentation reviews still happen as a single diff over an entire file, which makes it easy to miss a subtly wrong sentence in a medium-risk section. A section-level gate changes the failure mode: the model can only write inside explicitly allowed blocks, and every human-owned block must carry a verifiable sign-off stamp. The script checks the stamps in CI, so the process is reproducible instead of relying on memory.

The Draftability Criteria

Before writing any code, classify each section by whether the content is verifiable by execution, whether it encodes decisions, and whether mistakes have severe consequences. The following table summarizes the split:

Section type	Verifiable?	Decision-heavy?	Owner	Example
API endpoint reference	Yes (via runnable examples)	No	AI draft + review	Response codes, request fields
Configuration table	Yes (via schema check)	No	AI draft + review	Env vars, flags
Security model	No	Yes	Human	Threat model, trust boundaries
Migration strategy	No	Yes	Human	Breaking changes, rollback plans
FAQ	Partially	No	AI draft	Common errors
Design rationale	No	Yes	Human	Why we chose X over Y

The rule of thumb is that a section is AI-draftable only when you can construct an automated test that passes exactly when the section is correct. Human-owned sections are those where correctness depends on judgment, trade-offs, or institutional memory that the model does not have.

The Workflow: From Spec to Sign-Off

The pipeline runs on a free server so the generation job does not consume a local workstation, and the free model access keeps the marginal cost of iterating on drafts at zero. There is one crucial constraint: the model only ever fills AI-draftable placeholders, never human-owned blocks. The steps are:

Define a doc-spec.yaml that maps section IDs to ownership and review requirements. The script later reads this file as a single source of truth.
Create a Markdown skeleton that contains headings for every section, with a placeholder comment in AI-draftable sections and an explicit OWNERSHIP: human marker in human-owned sections.
Run a generation job on the free server using MonkeyCode's free model access. The job sends only the AI-draftable sections to the model, inserts the response, and leaves human-owned sections untouched.
Commit the result to a branch and let the ownership gate run in CI. The gate fails if a human-owned section has no REVIEW: stamp or if an AI-draftable section is missing its OWNERSHIP: ai marker.
A human reviews the diff, writes the human-owned sections (or corrects the AI drafts), and adds a review stamp like  to each owned block.
Merge only after the gate passes, which guarantees that every human-owned section has been explicitly touched by a named person.

The Ownership Gate Script

The artifact is a small Python script that reads the YAML spec and a generated Markdown file, extracts sections by ## headings, and checks ownership markers. You can run it locally or in CI.

#!/usr/bin/env python3
"""Section ownership gate for AI-drafted documentation."""
import re
import sys
from pathlib import Path

try:
    import yaml
except ImportError:
    sys.exit("PyYAML is required: pip install pyyaml")

def load_spec(path):
    data = yaml.safe_load(Path(path).read_text())
    return {s["id"]: s for s in data["sections"]}

def get_sections(md):
    pattern = re.compile(r"^## (.+)$(.*?)(?=^## |\Z)", re.MULTILINE | re.DOTALL)
    out = {}
    for slug, body in pattern.findall(md):
        out[slug.strip().lower().replace(" ", "-")] = body
    return out

def main():
    if len(sys.argv) != 3:
        print("usage: ownership_gate.py doc-spec.yaml generated.md")
        return 2
    spec = load_spec(sys.argv[1])
    sections = get_sections(Path(sys.argv[2]).read_text())
    failures = []
    for section_id, meta in spec.items():
        body = sections.get(section_id)
        if body is None:
            failures.append(f"Missing section '{section_id}'")
            continue
        if meta.get("owner") == "human":
            if "REVIEW:" not in body:
                failures.append(f"Human-owned '{section_id}' lacks REVIEW stamp")
        else:
            if "OWNERSHIP: ai" not in body:
                failures.append(f"AI section '{section_id}' missing ownership marker")
    if failures:
        print("\n".join(failures))
        sys.exit(1)
    print("All ownership gates passed.")

if __name__ == "__main__":
    raise SystemExit(main())

A corresponding doc-spec.yaml looks like this:

sections:
  - id: api-endpoints
    owner: ai
  - id: config-table
    owner: ai
  - id: security-model
    owner: human
  - id: migration
    owner: human

The gate is deliberately small because it is meant to be embedded in a CI step such as python ownership_gate.py doc-spec.yaml generated.md. You can extend it to verify that human-owned sections contain a date and reviewer identity, or to require a signed-off title pattern.

Limitations of the Ownership Gate

The script does not measure the quality of AI-drafted content; it only ensures that human-owned sections are verified. A false sense of safety appears when team members stamp a review without actually reading the section, so the gate should be paired with a code-review rule that treats stamps as attestations. The gate also cannot detect if the model leaked institutional facts into AI-draftable sections, because it only checks markers. For high-risk projects, add an extra human review of the final rendered output, not just the source Markdown.

Who Should Not Use This Workflow

Teams without a designated human owner for each section will see the gate fail repeatedly, and failing gates become noise. The same applies to projects where documentation must be approved as a single artifact by a compliant process, because section-level stamps may not satisfy an auditor. Lastly, if your documentation includes proprietary algorithms or customer-specific details, the free model access should not be pointed at those sections even if they are classified as AI-draftable; use a local or private model instead.

The generation step in this pipeline runs on MonkeyCode's free model access and their free server option, which keeps the marginal cost at zero. The pattern transfers to any other provider; the important part is the ownership split and the gate that enforces it. If you already have a documentation CI pipeline, add this gate before you spend one more review cycle on a full-file diff.

Draft the Stable, Own the Moving: A Change-Velocity Contract for AI-Generated Docs

Avery Lin — Mon, 31 Aug 2026 07:01:17 +0000

Most AI documentation workflows assign ownership by document type: tutorials go to the model, API references go to the engineering team, and migration notes go to platform owners. In a real repository, that split collapses within two release cycles, because a tutorial can carry one fragile version pin while a reference page quietly drifts every sprint. Responsibility ends up assigned by the name of the document rather than by how often its content actually changes or breaks. A better split replaces document type with change velocity, and the model drafts exactly the sections whose cost of going stale is lowest.

This article walks through a reproducible workflow: measure per-section churn from git history, tag each section with risk markers, and translate the two signals into a drafting contract the model must honor. The contract is not a promise made in a prompt, but a section-level permission list generated from measurable repository data.

A Cheaper Signal: Per-Section Churn

Most teams have no budget to measure how often each documentation sentence goes stale, but git history already provides a reasonable proxy. A section edited in every release needs a human who understands why that churn happens; a section untouched for two years may need no drafting budget at all. Git's -L line-range option gives a per-section commit count even when files are renamed, and the following script converts one Markdown document into a per-section scoring table.

#!/usr/bin/env bash
# section_churn.sh — approximate per-section commit counts for a Markdown doc.
# Usage: ./section_churn.sh docs/user-guide.md
set -euo pipefail
doc="$1"
python3 - "$doc" <<'PY'
import re, subprocess, sys

path = sys.argv[1]
lines = open(path, encoding="utf-8").read().splitlines()
heads = [(i + 1, ln.strip("# ").strip())
         for i, ln in enumerate(lines)
         if ln.startswith(("# ", "## "))]
if not heads:
    heads = [(1, path)]
heads.append((len(lines) + 1, None))

commit_re = re.compile(r"^[0-9a-f]{7,40} ")

for idx in range(len(heads) - 1):
    start, name = heads[idx]
    end = heads[idx + 1][0] - 1
    proc = subprocess.run(
        ["git", "log", "--oneline", "-L", f"{start},{end}:{path}", "--", path],
        capture_output=True, text=True, check=False,
    )
    n = sum(1 for l in proc.stdout.splitlines() if commit_re.match(l))
    print(f"{n}\t{name}")
PY

The output is a tab-separated table of commit counts per heading, which you can sort to find the sections that actually move. This is an approximation rather than a measurement, because large refactors or renames can flatten line history into one opaque chunk. Treat a low churn score as the beginning of a question, not as proof that a section is safe to automate, and check whether a quiet section is quiet because nobody reads it.

Turning the Numbers into a Drafting Contract

Churn alone is not enough; a stable section can still hold version pins, example URLs, or authentication notes that are expensive when wrong. Pair the commit count with content risk markers, and the decision table below decides which sections a model may draft.

Section churn	Risk markers	Drafting decision
Low	None: pure prose, stable references	Model drafts freely
Low	Version numbers, URLs, CLI syntax	Model drafts; a second pass verifies the pins
High	Config keys, local paths, failure modes	Human owns; the model may reformat the draft
High	API contracts, access control, migrations	Human writes; the model is not invoked

When you cannot explain why a section changes, move it one row to the right, because unexplained churn usually hides a contract that no one explicitly owns. Write the outcomes of that table into a small contract file that the drafting step reads before it starts:

# drafting_budget.yaml — section-level permissions for model drafting
drafting_budget:
  doc: docs/user-guide.md
  churn_baseline: 2026-08-31
  sections:
    - heading: "Authentication basics"
      decision: agent
    - heading: "Token renewal"
      decision: verify
      checks: ["grep for version pins", "confirm curl flags"]
    - heading: "Breaking changes"
      decision: human

The contract is the artifact that separates this approach from document-type heuristics: a section marked agent is a candidate for model drafting, a section marked verify needs a deterministic check, and a section marked human is excluded from the model context entirely. Re-run the churn script before each drafting cycle, because the contract is a snapshot of repository behavior, not a permanent constitution.

Making the Model Honor the Section Boundaries

A contract only works if the drafting step receives it, so extract the permitted headings into the model prompt with a small command rather than trusting the model to remember the file:

python3 -c "
import yaml
budget = yaml.safe_load(open('drafting_budget.yaml'))['drafting_budget']
allowed = [s['heading'] for s in budget['sections'] if s['decision'] == 'agent' or s['decision'] == 'verify']
print('\n'.join(allowed))
"

Put that list in the system context, and add one explicit rule: sections not listed are off-limits, and the model should say why it refused instead of editing them silently. When the draft comes back, run the verify checks, diff only the allowed sections, and reject any change that crosses a boundary defined in the file.

This stage is also where the cost model matters: the contract deliberately labels most sections as low risk, so the drafting run does not need an always-on or expensive pipeline. In my workflow, I use MonkeyCode's free model access and free server option to run the low-risk drafting steps, which keeps the per-cycle cost near zero while the human-owned sections stay untouched by the generation stage. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The workflow itself lives entirely in git history and the contract file, so the process still works without the product; the free options just make it cheap to iterate many times.

Limitations and Who Should Not Use This

This method assumes a repository with meaningful history, honest commit discipline, and sections that actually distinguish themselves in git. A repo with three large commits, a single monolithic deployment doc, or generated changelogs will produce a churn table that is noise; the script does not measure author intent, reviewer experience, or whether the churn was caused by a script renaming every heading. Teams that still manually approve every documentation change have nothing to optimize yet, and teams working on regulated or contractual text should keep the human gate on every word, regardless of what the numbers say.

The approach also breaks down when a file is large enough that git log -L becomes slow, so scope the script to one document at a time and accept that one giant refactor can inflate the count for every section touched. If the churn table consistently contradicts what maintainers feel about the doc, trust the maintainers and fix the history signal instead of rewriting the table.

Next time you split drafting responsibility, do not ask what category a document belongs to; ask how often each section changes and which string inside it is the most expensive to get wrong. When those two answers drive the split, a model drafts sections that are cheap to regress, and a human reviews the section that actually expresses the system's contract.

The Doc Draft Ledger: Price Verification Before You Send a Section to the Model

Avery Lin — Mon, 31 Aug 2026 03:59:01 +0000

The cheapest AI draft is the one a reviewer can verify in under two minutes. Most teams route an entire documentation set to a model and then discover that a single high-claim section consumes more review time than writing it by hand. The fix is a ledger that prices every doc section before the first generation job starts.

Why Verification, Not Drafting, Is the Bottleneck

Model output is a supply that outpaces human attention by orders of magnitude. With MonkeyCode's free model access and free server option, a first draft becomes a batch operation instead of a desk operation. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The real constraint is the minutes a human spends deciding whether each sentence is true, current, and safe to publish.

That asymmetry has a practical consequence for documentation teams. A two-thousand-word section may take the model twenty seconds to produce and a reviewer ninety minutes to validate. Review time does not scale with word count; it scales with the density of statements that can be wrong.

A contract says who owns a section, and a ledger says what ownership costs. The workflow below combines both: three ownership classes, a pricing formula, and a CI gate that fails when the estimated review load exceeds a weekly budget.

The Ledger Schema

The ledger is a YAML file with one entry per top-level doc section. Keep it in the repository so the check becomes part of the merge pipeline.

budget:
  weekly_review_minutes: 240

sections:
  - id: quickstart
    path: docs/quickstart.md
    class: draftable
    words: 900
    claim_density: low
    code_blocks: 2
    external_links: []
  - id: authentication
    path: docs/auth.md
    class: hybrid
    words: 1400
    claim_density: high
    code_blocks: 4
    external_links: ['https://example.com/spec']
  - id: deployment-topology
    path: docs/deployment.md
    class: owned
    words: 1200
    claim_density: high
    code_blocks: 6
    external_links: []

Three classes do the work in practice. draftable sections contain reproducible steps and low-stakes instructions, so the model may draft them and the human spot-checks. hybrid sections carry real technical weight, so the model produces an outline and example code while the human writes the final prose. owned sections cover architectural, security, or contractual claims and stay human-authored from the first keystroke.

The Verification Price

The ledger turns each section into an estimated review cost using weights, not magic. A claim about 'always' or 'never' costs more than a claim about 'can be' because one counterexample invalidates it. Every code block adds a read-and-run tax, and every external link adds a broken-reference risk.

#!/usr/bin/env python3
"""ledger_check.py - price doc verification before the model drafts anything."""
import argparse
import sys

try:
    import yaml
except ImportError:
    sys.exit('pip install pyyaml first')

WEIGHTS = {
    'claim_minutes': {'low': 1, 'medium': 3, 'high': 8},
    'code_minutes': 3,
    'link_minutes': 1,
    'read_wpm': 220,
}
CLASS_MULTIPLIERS = {'draftable': 0.3, 'hybrid': 0.7, 'owned': 0.0}


def section_cost(sec):
    claim = WEIGHTS['claim_minutes'][sec.get('claim_density', 'low')]
    code = WEIGHTS['code_minutes'] * sec.get('code_blocks', 0)
    links = WEIGHTS['link_minutes'] * len(sec.get('external_links', []))
    read = sec.get('words', 300) / WEIGHTS['read_wpm']
    base_minutes = claim + code + links + read
    return base_minutes * CLASS_MULTIPLIERS.get(sec['class'], 0.7)


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('ledger', type=str)
    parser.add_argument('--budget', type=int, required=True,
                        help='weekly AI-review budget in minutes')
    args = parser.parse_args()

    with open(args.ledger, 'r', encoding='utf-8') as fh:
        data = yaml.safe_load(fh)

    rows = []
    ai_total = 0.0
    docs_total = 0.0
    for sec in data['sections']:
        cost = section_cost(sec)
        ai_cost = cost if sec['class'] != 'owned' else 0.0
        rows.append((sec['id'], sec['class'], round(cost, 1), round(ai_cost, 1)))
        ai_total += ai_cost
        docs_total += cost

    print(f"{'section':<16} {'class':<12} {'all min':<8} {'ai min':<8}")
    print('-' * 48)
    for ident, klass, cost, ai_cost in rows:
        print(f'{ident:<16} {klass:<12} {cost:<8} {ai_cost:<8}')
    print('-' * 48)
    print(f'AI-drafted verification estimate: {ai_total:.1f} min')
    print(f'Budget: {args.budget} min')

    if ai_total > args.budget:
        sys.exit(f'OVER BUDGET by {ai_total - args.budget:.1f} min')
    print('Within budget.')


if __name__ == '__main__':
    main()

The script is a reference implementation, so treat the weights as starting points rather than measured facts. Its purpose is to make the trade visible before anyone reads generated prose.

Running it on the ledger above produces a short table:

section           class          all min  ai min
------------------------------------------------
quickstart        draftable      3.8      1.1
authentication    hybrid         12.6     8.8
deployment-topology owned        16.2     0.0
------------------------------------------------
AI-drafted verification estimate: 9.9 min
Budget: 240 min

The authentication section alone consumes most of the AI-review allowance, and the owned deployment section costs nothing against that budget. If the sum exceeds the weekly budget, the command exits non-zero and the merge pipeline stops before anyone opens a draft.

The Six-Step Workflow

Use the ledger with a short loop that keeps human attention in the loop.

Inventory. Find the top-level sections of your doc set and record their word counts, code blocks, links, and claim density. A quick start is find docs -name '*.md' -exec wc -w {} + plus a manual pass for claim density.
Classify. Assign each section to draftable, hybrid, or owned based on how much harm a wrong statement could cause.
Draft. For draftable and hybrid sections, run the generation job against MonkeyCode's free server option with its free model access, and write the output to a feature branch. Keep owned sections on the keyboard; a model never sees them.
Price. Run python3 ledger_check.py docs_ledger.yaml --budget 240 and read the resulting table.
Cut, don't stretch. If the estimate is over budget, move the costliest section to owned or delete it from the sprint. Never lower the budget to match the output, because that defeats the exercise.
Verify and merge. For every section the model touched, add verified_by and verified_on fields to the ledger; the ownership gate can refuse to merge until those fields exist.

Calibration Notes

The default weights are heuristics, so calibrate them with your own review history. Pick five merged doc PRs, record the actual review minutes, and divide by the estimate the script produced before merge. If the ratio is consistently around 1.4, raise every weight by that factor; if it is below 0.8, lower them. Two weeks of data is enough to stop guessing about verification cost.

Limitations and Non-Fit

The ledger cannot measure comprehension, so a cheap section can still mislead a reader. The free tier is a development resource and not an SLA, so availability and quotas can change during a sprint; keep a fallback path ready. Skip this workflow when your docs are mostly narrative, because classifying prose-heavy pages costs more than the drafting saves. Skip it when no one is actually reviewing, because the ledger exposes a time deficit but cannot create capacity.

Close

Price the review, not the generation. Run the reference script against a repo you maintain with a two-hour budget and read the first overrun report; it will teach you more about your AI documentation workflow than the next model evaluation.

The AI Draft Is a Hypothesis: A Claim-Tagged Documentation Workflow

Avery Lin — Mon, 31 Aug 2026 00:52:01 +0000

The useful way to read AI-generated documentation is as a collection of tagged hypotheses, not accepted facts. Clarity does not imply truth, so the only durable review question is whether each claim traces to a human decision. This article shows a workflow that forces that traceability.

Generated docs fail in a predictable pattern: the prose reads smoothly, the example looks plausible, and the critical assumption hides inside a transition sentence. Traditional review asks whether the text sounds right, but sound prose can still ship a destructive command. The stronger review asks whether every factual statement has an evidence trail.

MonkeyCode offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two availability facts matter because they make the workflow cheap to test, but the method itself depends only on a model that can emit markers and a reviewer who wants evidence.

The ownership split

A practical split has three zones.

The model may draft explanatory prose, parameter descriptions, and usage patterns derived from files you provide. These are cheap to regenerate when wrong.
The human must own state-changing commands, security and compliance statements, and claims about external behavior. These carry the highest verification cost.
Both may contribute code blocks, but the human must confirm that every example runs in the documented environment.

The split is really about verification cost, not word count. Prose is easy to fix after a mistake, while a wrong rm instruction can destroy data in minutes.

The claim marker

The generation prompt asks the model to place a marker above every factual sentence or example. The marker contains an ID, a type, and a placeholder status. The model cannot fill in evidence; that slot belongs to a person.

## Uninstall

To remove the tool, run:

<!-- CLAIM:uninstall-command type=operational status=unverified -->

toolname remove --all

The prompt instruction can be as short as this:

For each factual claim or command in the output, add an HTML comment
`<!-- CLAIM:<id> type=<type> status=unverified -->` directly above it.
Allowed types: operational, security, behavior, performance.
Do not claim a fact unless it appears in the provided source material.

Without such a marker, a generated sentence such as "this removes all cached data" looks like documentation. With a marker, it looks like a claim waiting for proof.

The evidence ledger

Every claimed ID gets a row in docs/evidence.yaml. The ledger is the source of truth for what a human actually checked.

uninstall-command:
  claim: "toolname remove --all deletes config and cache"
  type: operational
  status: verified
  owner: "Avery Lin"
  evidence: "https://ci.example.com/jobs/42#step-7"

install-command:
  claim: "Requires Python 3.9 or newer"
  type: behavior
  status: unverified
  owner: null
  evidence: null

A row moves to verified only when evidence points to a log, a test, or an issue that a human read. The model's confidence is not evidence; a recorded human decision is.

The gate

A small script can enforce this contract in CI. The script extracts markers, looks up each ID in the ledger, and fails the build when a claim is missing or still unverified.

import re
import sys
import yaml

PATTERN = re.compile(r"<!-- CLAIM:(\S+) type=(\S+) status=(\S+) -->")

def main(path: str, ledger_path: str) -> int:
    with open(ledger_path) as f:
        ledger = {k: v for k, v in yaml.safe_load(f).items()}

    missing, unverified = [], []
    with open(path) as f:
        for match in PATTERN.finditer(f.read()):
            claim_id = match.group(1)
            if claim_id not in ledger:
                missing.append(claim_id)
            elif ledger[claim_id]["status"] != "verified":
                unverified.append(claim_id)

    for claim_id in missing:
        print(f"missing in ledger: {claim_id}")
    for claim_id in unverified:
        print(f"not verified: {claim_id}")
    return 1 if missing or unverified else 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1], sys.argv[2]))

That gate does not verify whether the code blocks run. It checks something simpler and more fundamental: whether a person has signed off on each claim before the prose enters the default branch. For multiple files, run the script once per file and aggregate the failures.

Workflow order

The full process fits into five ordered steps.

Write a list of atomic requirements in your issue tracker, such as "the upgrade command must not stop a running service."
Give the model a section of code and the related requirement ID, then request a draft with markers.
Run the extraction script and export every unverified claim into docs/evidence.yaml.
For each unverified claim, find evidence in build logs, test outputs, or issue history, then update the row with an owner and a URL.
Re-run the gate. When it is green, read the prose once for tone and for contradictions that markers cannot capture.

The order matters because evidence collection becomes the review. Instead of reading the document top to bottom, the reviewer reads a claim list and dispatches items one by one. The prose still gets read, but the high-risk work happens inside the ledger.

Who should not use this

Teams without any decision record will find this workflow annoying. If there is no issue history or CI log to point at, the evidence column stays empty and the gate stays red. A single developer producing undocumented scripts will also not benefit, because the overhead of maintaining a ledger can exceed the value of the docs. This workflow fits projects where documentation is consumed daily and a wrong instruction has measurable cost.

Limitations

This system does not verify anything automatically; instead it makes review explicit and auditable. The model can still hide a false claim in surrounding prose, and the marker only makes that claim an easier review target. Free-tier generation also has practical limits that depend on current service policies, so treat the workflow as model-agnostic and validate it before adopting it at scale.

Try the claim marker on your next docs pull request and watch the review conversation change. The first debugging session that ends with "who marked this verified?" is the moment the ledger pays for itself.

Stale Docs Are a Context Problem: Build a Staleness Detector on a Free Server

Avery Lin — Sun, 30 Aug 2026 21:50:14 +0000

Liquid syntax error: Unknown tag 'endraw'

Two Pockets, One Doc: A Draft-Budget Workflow for AI-Generated Documentation

Avery Lin — Sun, 30 Aug 2026 18:46:25 +0000

The bottleneck in AI-assisted documentation is not generation; it is the review queue. A model can rewrite a paragraph in seconds, but a human still decides whether that paragraph is true, useful, and safe to ship. In practice, teams do not fail because the model wrote too much; they fail because they reviewed too much generated prose and too few real decisions. A draft budget solves this by labeling sections before the first prompt is sent.

A draft budget is a per-document rule that assigns every section to one of two pockets: model may draft or human must own. The model fills its own pockets and nothing else. The human reviews only the owned sections and the seams between pockets. This is different from an ownership matrix, which describes who approves content; a draft budget describes what content the model is allowed to produce at all.

In this workflow I use MonkeyCode's free model access and the free server option to run small drafting iterations without a compute budget. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The Draft Budget Artifact

The core artifact is a small YAML file that reads like a contract between you and the model. It names each section, its owner, the allowed output shape, and the prompt template. Here is a realistic example for a library that describes a JavaScript data-masking utility:

version: 1
sections:
  quick-start:
    owner: model
    prompt: "Write a 3-line code example that masks an email with maskData(). Output only code."
    accepts: code
  error-matrix:
    owner: model
    prompt: "List the five most common maskData() errors and a one-line fix for each. Use bullets."
    accepts: bullets
  performance-rationale:
    owner: human
    forbid: "Do not mention benchmarks, trade-offs, or measured latency."
    requires: human-drafted
  security-note:
    owner: human
    forbid: "Do not suggest workarounds for built-in limitations."
    requires: human-drafted
acceptance:
  max_model_sections: 2
  min_human_owned_ratio: 0.3

A Small Script That Enforces the Budget

The file only helps if something reads it. This Python script turns the budget into a prompt queue and a post-generation check. It does not call any API; it prints the exact prompt for each model-owned section and marks the rest as human-owned.

import sys
import yaml

def load_budget(path):
    with open(path) as f:
        return yaml.safe_load(f)

def build_queue(budget):
    queue = []
    for name, spec in budget["sections"].items():
        if spec.get("owner") == "model":
            queue.append((name, spec["prompt"]))
        else:
            queue.append((name, None))
    return queue

if __name__ == "__main__":
    budget = load_budget(sys.argv[1])
    for name, prompt in build_queue(budget):
        if prompt:
            print(f"# {name}\n{prompt}\n")
        else:
            print(f"# {name}\n[HUMAN-OWNED] draft your own text.\n")

After generation, a second check ensures the model did not wander into a human-owned section. You can implement this as a GitHub Action that greps for forbidden markers, or as a lint rule that verifies [HUMAN-OWNED] placeholders were replaced only by a human. The exact mechanism matters less than the invariant: if a diff touches a human-owned section, the author field must be a human, not the model.

The Five-Step Workflow

List the sections and assign owners. Start with the table of contents, not with a blank prompt. Mark examples, repetitive error lists, and command references as model. Mark rationale, trade-offs, security notes, and anything with legal weight as human.
Write section-level prompts with output shapes. A prompt like write a page about masking is a blank page, not a pocket. Give the model a section name, a length, and an allowed format: code block, bullet list, or a short paragraph. The budget YAML above is an example of this discipline.
Generate model-owned sections on the free tier. Because the drafting loop is small and iterative, you do not need a paid remote session. MonkeyCode's free server option places the agent in a sandbox, and the free model access covers the quick-start and error-matrix pockets.
Run the boundary check. Paste the generated output back into the document, then run the script that verifies no model-owned section contains forbidden terms and no human-owned section was filled by the agent. This step fails loudly instead of leaving you to guess who wrote what.
Review only the human-owned seams. Your review time is now spent on decisions, not prose: Is the trade-off honest? Does the security note include the right caveat? Does the performance rationale reflect measured evidence? Those are the only sections that require deep attention.

Limitations and Who Should Not Use This

This workflow assumes you can label sections before a single draft exists. That is easy for reference documentation, API guides, and migration notes; it is hard for exploratory writing where the best structure emerges only after the text exists. If you are writing a design proposal that changes shape during drafting, a rigid budget will slow you down.

The budget also does not verify factual correctness. A model-owned example can still be wrong, and a human-owned rationale can still cite fake numbers. Pair this workflow with the executable-docs gate from earlier work in this series, where every code block is run before merge. For security advisories, legal disclaimers, or anything where a single wrong word creates liability, do not let the model produce prose at all; keep the entire document in the human pocket.

A draft budget is not a permission slip for the model to be lazy. It is a permission slip for you to stop reviewing the parts that do not decide the product's truth. When you move the review from prose to decisions, documentation stops being a bottleneck and starts being a fast, low-risk output channel.

The 2-Edit Rule for AI-Drafted Docs: A Free-Tier Workflow That Keeps Humans Responsible

Avery Lin — Sun, 30 Aug 2026 15:45:33 +0000

If you let a model draft your documentation, you need a rule that forces a human to actually reshape it—otherwise you are shipping a claim nobody signed. The 2-Edit Rule is one such mechanism: every section drafted by a model must be followed by at least two human-made line edits that are not part of the draft contract. This article shows why a rule based on observable edits beats trust, how to enforce it with a small CI script on free infrastructure, and where the rule falls apart.

The autopilot problem

When a model writes a paragraph that sounds exactly like your team’s style guide, the reviewer’s brain switches to autopilot. Many teams merge README changes that contain hallucinated function names, because the prose was convincing enough. Labels like  help, but they are passive. They tell a reviewer what to look at, not what to do.

The 2-Edit Rule changes that. For every document section that the model drafts, a human must introduce at least two non-trivial line changes before CI permits the merge. One edit proves the human actually read the section. The second edit proves they understood it well enough to correct, reorder, or extend it. The rule is deliberately minimal, but it creates a verifiable artifact: a diff that did not come from the model.

Why two edits, not one

A single edit can be a typo fix or a whitespace change. Two edits that survive a conversation with the model—for example, a corrected function signature and an added warning paragraph—are much harder to fake accidentally. You can tune the threshold to your team’s risk appetite; the key is that the rule is mechanical, not moral. It does not trust the reviewer’s self-report. It inspects the PR.

What the model may draft, what a human must own

The rule works best when you split the document into bands before generating anything:

Band	Content examples	Who owns it
1. Prose & structure	Explanation of a concept, section ordering, default examples	The model may draft, human may restructure
2. Code-adjacent facts	Function signatures, dependency versions, error codes	Human must verify and replace placeholders
3. Commitments	Security guarantees, performance claims, migration steps	Human must write or explicitly approve

In practice, this means the model writes band one freely, but for bands two and three it emits FIXME(<id>) markers instead of confident text. The CI script then counts human edits on those markers. You tell the model to use markers, and you tell your human reviewers that a merge without resolving them is a process failure.

A minimal free-tier pipeline using free model access

The pipeline has four moving parts: a scheduler, a model call, a PR, and a CI check. On a free server you can run all four without spending anything.

A scheduled job inspects the repository’s recent commits and selects files that need doc updates.
You call your model provider—for example, MonkeyCode’s free model access—to produce a first draft for those files. Mark every drafted section with a unique header like .

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The draft is committed to a PR.
CI runs check-human-edits.sh, which fails if any Draft:-marked file has fewer than two human-authored line changes outside the marker lines.

The script itself is deliberately small:

#!/usr/bin/env bash
# check-human-edits.sh - fail if AI-drafted sections have <2 human edits
set -euo pipefail

threshold=${1:-2}
fail=0

# Find files touched by the PR (here: files changed vs main)
changed_files=$(git diff --name-only origin/main...HEAD)

for file in $changed_files; do
  [[ "$file" == *.md ]] || continue
  if ! grep -q "Draft: model-" "$file"; then
    continue
  fi

  # Count added lines that do not come from the model's watermark
  added_lines=$(git diff origin/main -- "$file" | grep '^\+' | grep -v '^\+\+\+' || true)
  human_edits=$(echo "$added_lines" | grep -v "Draft: model-" | grep -v '^\+<!--' | grep -v '^\+$' | wc -l)

  echo "File $file: $human_edits human edits"
  if [[ "$human_edits" -lt "$threshold" ]]; then
    echo "❌ Human must add at least $threshold meaningful edits to $file"
    fail=1
  fi
done

exit $fail

This is a starting point, not a universal solution. The script filters out lines that only add the model marker, comment markers, or blank lines. You will almost certainly want to exclude code fences and reuse your own comment conventions. But the shape is correct: you count added lines that are not branded.

Running the check on free infrastructure

The script runs in any POSIX environment. On GitHub Actions, a minimal workflow triggers on pull requests:

name: docs-edit-check
on: pull_request
jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: bash check-human-edits.sh 2

The same YAML can run on a self-hosted runner or on MonkeyCode’s free server option if you prefer to keep your CI in one place. The only dependency is git.

Where the rule breaks

The 2-Edit Rule is not a magic gate. It fails when the human edits are fake—for instance, when a reviewer splits a line into two just to pass the count. To counter that, you can raise the threshold, require edits that contain at least one identifier from the surrounding code, or run a code-block compile check alongside it. For a brand-new project with no existing docs and no tests, the rule can feel like busywork: a two-line README might get meaningful human edits anyway, but a four-hundred-page API reference would need a different partitioning.

The rule also cannot tell whether a human’s edits are correct. It only proves attention. For that reason you still need example execution, link checking, and a real reviewer. Think of the 2-Edit Rule as a floor, not a ceiling.

Who should not use this

Do not use this rule if your team treats docs as a low-risk, quickly-iterated artifact that anyone can change freely—or if you have no model in the loop at all. If you do use it, pair it with a clear statement of what the model is allowed to draft: stable, reference-like text can be drafted fully; any behavioral promises, dependency versions, and security warnings must be owned by a human. The rule simply makes that ownership observable.

Wrapping up

The 2-Edit Rule converts the vague instruction “review the AI docs” into a countable CI gate. It works because it attacks the root failure mode of AI-assisted writing: fluent prose that nobody actually evaluated. Add a cheap model for drafting and a free CI minute for checking, and you have documentation that carries at least one human signature—two, if the team is honest.

That is a workflow worth trying when your next model-generated PR lands on your desk.

Token Budgets as Ownership Controls: A Free-Tier Docs Drafting Service

Avery Lin — Sun, 30 Aug 2026 11:35:43 +0000

Free AI infrastructure makes generated documentation cheap, but cheap text accumulates into unowned liabilities far faster than review capacity does. The practical countermeasure is not to slow down generation but to encode ownership directly into the allocation of tokens and the shape of the merge gate. This article shows how to build a small documentation drafting service on MonkeyCode's free model access and free server option, where every generated paragraph must carry a named human owner before it can pass CI. The result is an AI-assisted pipeline that keeps the human in control without requiring a large budget or a dedicated GPU.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode provides a free model access tier (currently advertised with a 10-million-token allowance) and a free server option, which I used as the run-time foundation for the workflow below.

The Problem: More Drafts, Less Ownership

When the marginal cost of a paragraph drops to nearly zero, teams generate dozens of doc pages that nobody explicitly accepted. The usual aftermath is a wiki full of plausible prose with no clear responsible person when the content drifts out of date. A Draft/Own contract solves part of that by stating who owns what, but it remains a document in isolation unless the pipeline enforces it. The enforcement levers are the same resources that made generation cheap: the token budget and the server that runs the generator.

The Architecture: A Small Gateway with a Budget File

I propose a minimal service that sits between a documentation request and a final merge. It reads an ownership.yaml file, calls the model through MonkeyCode's documented API, and returns a Markdown draft where each section is annotated with an owner field. The server runs on MonkeyCode's free server option, which is enough for a low-traffic internal tool. The CI pipeline then verifies three conditions: every top-level section has an owner, the total token consumption stays under the per-request budget, and no section was drafted when the policy marks it as human-only.

Here is the core configuration file that defines the boundary for a typical project:

# ownership.yaml
budget:
  max_tokens_per_request: 1500
  max_tokens_per_section: 300
sections:
  getting-started:
    ai_draft: true
    owner: "@pavel"
  architecture:
    ai_draft: false
    owner: "@maria"
  troubleshooting:
    ai_draft: true
    required_review: "@ravi"

The ai_draft: false flag is the most important line in the file. It tells the generator to leave that section untouched, even when it receives a broad request. The budget numbers act as a cost-aware proxy for ownership: if a human-only section accidentally sneaks into the prompt, the token accounting will reveal the extra consumption.

Building the Drafting Service

The service itself is a small Python application with two endpoints. The first endpoint accepts a topic and a section list, resolves the corresponding policies, and calls the model only for sections where ai_draft is true. The second endpoint returns the generated draft with an ownership matrix that CI can validate. I wrote the prototype below against a generic model interface, so it works with MonkeyCode's free model access once you supply the endpoint and key from your project settings.

# draft_service.py
import yaml
from typing import Dict, List

def load_policy(path: str) -> Dict:
    with open(path) as f:
        return yaml.safe_load(f)

def draft_sections(policy: Dict, requested: List[str]) -> Dict:
    result = {}
    used_tokens = 0
    for section in requested:
        conf = policy["sections"].get(section)
        if not conf or conf.get("ai_draft") is False:
            result[section] = {"status": "human-needed", "owner": conf.get("owner") if conf else None}
            continue
        prompt = f"Write the {section} section of internal documentation."
        # model_call is a placeholder for MonkeyCode's text generation endpoint
        output = model_call(prompt, max_tokens=policy["budget"]["max_tokens_per_section"])
        used_tokens += output["usage"]["total_tokens"]
        result[section] = {"status": "ai-draft", "text": output["text"], "owner": conf["owner"]}
    result["_token_used"] = used_tokens
    return result

def model_call(prompt: str, max_tokens: int):
    # Replace with your authenticated request to MonkeyCode's API
    pass

The placeholder model_call is deliberate because the exact API URL and authentication format depend on the current MonkeyCode release, which the project documents in its README. This keeps the example honest about the integration seam while making the ownership logic fully runnable.

The CI Gate That Tests Ownership

Drafting alone does not create accountability. The merge gate runs a small checker that fails the build when any section lacks an owner or when a human-only section contains AI-authored content. The checker reads the same ownership.yaml file, so the policy cannot drift between the design document and the actual pipeline.

# .github/workflows/doc-ownership.yml
name: doc-ownership
on:
  pull_request:
    paths: ["docs/**"]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python check_ownership.py docs/ ownership.yaml

The check_ownership.py script is short, but it enforces the contract by scanning every generated Markdown file for an owner= metadata line and recomputing the token estimate from the length of the text. If a section is marked ai_draft: false and the file still contains generated-looking prose, the check fails. The exact heuristics are crude, but they catch the common failure mode where a request label leaks into the wrong document.

Where This Breaks Down

The approach is intentionally narrow and it has several limits. First, the token budget only measures input and output tokens, not the human time spent reviewing the text, so it cannot fully replace a qualitative review. Second, the ownership check relies on metadata that a determined contributor can fake, which means the gate is a safety net, not a grade for accuracy. Third, MonkeyCode's free server runs with constraints on uptime and concurrency, so this setup suits internal doc experiments more than customer-facing documentation at scale. Teams that need legally binding or legally reviewed documentation should not use this workflow until a human attorney verifies every generation.

Should You Try This?

You should adopt this pattern if your team already trusts AI for internal drafts but struggles with accountability for stale content. You should avoid it if you need publication-grade prose with regulatory requirements, because no token budget can replace the judgment of a licensed reviewer. For the rest of us, the free model allowance and the free server are enough to test the ownership-first approach on one small repository. If you decide to run it, start with a single ownership.yaml file and one docs folder, then expand after two weeks of successful merges.