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

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.

1. The model may draft explanatory prose, parameter descriptions, and usage patterns derived from files you provide. These are cheap to regenerate when wrong.
2. The human must own state-changing commands, security and compliance statements, and claims about external behavior. These carry the highest verification cost.
3. 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.

1. Write a list of atomic requirements in your issue tracker, such as "the upgrade command must not stop a running service."
2. Give the model a section of code and the related requirement ID, then request a draft with markers.
3. Run the extraction script and export every unverified claim into docs/evidence.yaml.
4. For each unverified claim, find evidence in build logs, test outputs, or issue history, then update the row with an owner and a URL.
5. 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.