The Draft/Own Contract: A Verification-Cost Split for AI-Generated Documentation

The line between AI-drafted and human-owned documentation is not about prose quality; it is about verification cost. A model can produce a perfect-sounding paragraph that is expensive to disprove, and a human can review a trivial example that costs nothing to trust. The practical workflow is to classify every section by two numbers: the cost of being wrong and the cost of verifying the content. When verification is cheap and failure is low-impact, the model may draft. When either condition fails, a human must own the section. This article defines a minimal contract format and a script that turns that split into a machine-readable workflow, using a free-tier AI tool to draft only the low-risk sections.

I have spent the last week iterating on the idea of section-level ownership for generated docs, and the recurring failure is not missing sections; it is the absence of an explicit boundary. Teams tell the model to "document the API" and then skim the output, which is neither drafting nor owning. A better approach is to decide before generation which sections fall into each category. The contract below encodes that decision so it can be reviewed, committed, and enforced.

The Verification-Cost Model

Every documentation section has two hidden costs. The first is the failure cost: if this section is wrong, what breaks? A typo in a code sample might waste five minutes, while a wrong parameter name in a public API contract could break every consumer. The second is the verification cost: how long does a competent human need to confirm the section is correct? A table of environment variables can be checked by grep; a concurrency model needs design-level reasoning.

The model may draft a section only when both costs stay below a threshold you define. In practice, that usually means sections like installation steps, configuration keys, common error messages, and ready-to-run examples. The human owns sections like authorization semantics, backward-compatibility guarantees, data retention policies, and any claim that a customer will rely on without reading the source code.

This is not a new distinction, but it is rarely made explicit. The artifact I propose is a docs_contract.yaml file at the root of your docs folder, plus a small Python script that reads it and prints the draft list for the model.

Step 1: Inventory the Sections

Create a YAML file that lists every major section of your documentation with two numeric fields. The first, failure_cost, ranges from 1 (a wrong example that is obviously wrong) to 5 (a wrong statement that causes data loss or legal liability). The second, verify_minutes, is your estimate of how many focused minutes a senior reviewer needs to confirm the content.

Here is a realistic example for a small internal API:

# docs_contract.yaml
sections:
  - path: getting-started/installation.md
    failure_cost: 2
    verify_minutes: 5
  - path: getting-started/quickstart.md
    failure_cost: 3
    verify_minutes: 15
  - path: api/authentication.md
    failure_cost: 5
    verify_minutes: 60
  - path: api/endpoints/users.md
    failure_cost: 4
    verify_minutes: 30
  - path: ops/environment-variables.md
    failure_cost: 2
    verify_minutes: 3
  - path: architecture/concurrency-model.md
    failure_cost: 5
    verify_minutes: 120

draft_threshold:
  max_failure_cost: 3
  max_verify_minutes: 20

The draft_threshold block is your policy. In this case, any section with a failure cost above 3 or a verification time above 20 minutes becomes human-owned. Only the remaining sections are candidates for AI drafting.

Step 2: Run the Splitter Script

The following Python script reads that YAML, applies the threshold, and outputs two lists. It also writes a docs_contract.md file that records the decision for future reviewers.

import yaml
from pathlib import Path

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

def split_sections(contract):
    threshold = contract["draft_threshold"]
    draft = []
    own = []
    for section in contract["sections"]:
        if (section["failure_cost"] <= threshold["max_failure_cost"] and
            section["verify_minutes"] <= threshold["max_verify_minutes"]):
            draft.append(section)
        else:
            own.append(section)
    return draft, own

def write_contract_md(draft, own):
    lines = ["# Docs Ownership Contract", ""]
    lines.append("## AI Draft")
    for section in draft:
        lines.append(f"- [ ] {section['path']} (failure={section['failure_cost']}, verify={section['verify_minutes']}m)")
    lines.append("")
    lines.append("## Human Own")
    for section in own:
        lines.append(f"- [ ] {section['path']} (failure={section['failure_cost']}, verify={section['verify_minutes']}m)")
    Path("docs_contract.md").write_text("\n".join(lines))

if __name__ == "__main__":
    contract = load_contract("docs_contract.yaml")
    draft, own = split_sections(contract)
    print("DRAFT sections for the model:")
    for s in draft:
        print(f"  {s['path']}")
    print("OWN sections for humans:")
    for s in own:
        print(f"  {s['path']}")
    write_contract_md(draft, own)

Run it with python split_contract.py. The output immediately tells your team which files to send to the model and which files to lock behind a human author. docs_contract.md becomes the single source of truth for the next review cycle.

Step 3: Generate Only the Draft List

This is where a free-tier AI tool becomes genuinely useful. MonkeyCode offers free model access and a free server option, which means you can run the drafting step without provisioning a remote API account. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Paste the draft list into MonkeyCode and ask it to write only those files. The prompt should include the section path, the intended audience, and the source material that already exists. For example:

Draft the file ops/environment-variables.md. Audience: backend operators.
Source: the .env.example file and the README section on configuration.
Do not invent flags that are not in the source material.

The free server option matters because the source files often contain internal paths and package names. Running on a free server keeps that context in your own execution environment instead of sending it to a third-party endpoint, though you should still check the terms of whatever deployment you choose.

Step 4: Human Review the Own List

The sections in the own list are non-negotiable. They require a named owner and are not eligible for merge until that owner signs off. This is not about mistrusting the model; it is about the cost asymmetry. A reviewer can spend two hours verifying a concurrency model, and the model only saved ten minutes of initial drafting. The human should write that section from scratch because the verification cost is indistinguishable from writing cost.

For the drafted sections, do not skip review entirely. Use the contract as a checklist: confirm the model did not drift into a topic that belongs to the own list. A model may happily explain authentication semantics inside an installation guide, and now you have a drafted section that needs a human anyway.

Limitations and Who Should Not Use This

The threshold numbers are estimates, not measurements. If your team systematically underestimates verify_minutes, the model will draft sections that silently consume senior hours. You should calibrate the values after one real review cycle, not on day one. The script also assumes YAML is an acceptable format for your repository; if your docs live in a CMS or wiki, the same logic applies but the automation needs a different adapter.

Do not use this workflow in domains where the cost of a wrong section is not expressible as a small integer. Regulated industries, public SDKs with contractual uptime promises, and security documentation all belong in the full-own category regardless of your threshold. Similarly, if you are drafting documentation for a system that does not yet exist, the verification cost is effectively infinite because there is nothing to verify against.

The Draft/Own Contract is not a permission slip to stop reviewing; it is a budget that forces you to spend human attention where the risk lives. By making the split explicit, you turn a vague ownership discussion into a file that can be reviewed, disagreed with, and improved.

If you already maintain an ownership boundary in a README or a wiki page, try encoding it with this YAML shape for one release cycle. The only thing you lose is the ambiguity.