The Draft Boundary: A Risk-Tiered Review Workflow for Generated Docs

A single draft-and-sign ceremony treats every generated sentence as equally risky, so reviewers either waste time on parameter lists or miss a broken security claim. The useful boundary is not one binary split but a graded tier per section, where the tier decides what the model may draft and what a human must own. This article defines three tiers, shows the decision table behind them, and ships a gate script that combines ownership checks with a review-budget estimate.

A two-party workflow, model drafts and human signs, fixed the worst failures of fully automatic publishing. It still routes a glossary entry and a compatibility promise through the same ceremony, even though their failure costs differ by orders of magnitude. An ownership check tells you whether a human owns the document, but it does not tell you which sections need the most expensive human attention. The missing piece is a graded boundary that maps every section to its failure cost before generation starts.

The failure cost decides the tier

A wrong parameter name costs a reader a few minutes of confusion, while a wrong security note can break a compliance review or trigger a production incident. A policy that spends equal effort on both is inefficient by construction, and a policy that skips both is reckless by design. Grading sections by failure cost yields three stable tiers that are easy to explain to any team.

Tier 1, mechanical: API parameter lists, glossary entries, and changelog skeletons fail cheaply, so the model may draft them and a linter can verify them against the codebase. Tier 2, runnable: tutorials, migration guides, and configuration walkthroughs fail the moment a reader copies them, so the model drafts but a human must run and edit every example. Tier 3, owned: security notes, compatibility promises, and pricing or SLA wording fail expensively, so a human must author them and the model may only suggest alternatives.

Section type	Tier	Who writes it	Verification gate	Review budget
API parameter list, glossary, changelog	1	Model	Mechanical lint against code	0.5 min/page
Tutorial, migration guide, config walkthrough	2	Model draft + human edit	Every example runs in CI	5 min/page
Security notes, compatibility, SLA wording	3	Human only	Two-person approval required	20 min/page

A five-step workflow for the boundary

1. Mark every section before drafting starts. Add a tier comment at the top of each section, so the model receives its responsibility contract inside the prompt.
2. Draft by tier, not by document. Instruct the model to generate Tier 1 and Tier 2 sections while leaving Tier 3 sections as empty stubs with an owned-by: line naming a maintainer.
3. Run the gate script in CI. The script rejects any draft that skips the boundary, verifies that every Tier 3 stub has an owner, and prints the predicted review budget for the change.

MonkeyCode's free model access lowers the cost of the draft loop, so regenerating Tier 1 and Tier 2 sections on every pull request becomes practical, and the free server option keeps that generation outside your local environment. The tiering logic is product-agnostic, so the workflow survives any change in the tools around it.

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

1. Spend the printed budget with intent. Perform mechanical checks on Tier 1, run and edit examples on Tier 2, and write Tier 3 content in full before requesting a second reviewer.
2. Measure and reclassify every cycle. Track the real review minutes per tier, compare them with the predicted values, and move any section whose failure cost does not match its tier.

The gate script

Copy this into scripts/tier_gate.py and point it at your docs directory. It reads every Markdown file, extracts the tier markers, and fails CI when a Tier 3 section has no explicit human owner.

#!/usr/bin/env python3
"""tier_gate.py — enforce the draft boundary and print the review budget."""
import json, re, sys
from pathlib import Path

BUDGET_MIN = {"1": 0.5, "2": 5, "3": 20}
TIER_RE = re.compile(r"<!--\s*tier:\s*([123])\s*-->")
SECTION_RE = re.compile(r"<!--\s*tier:\s*3\s*-->(.*?)(?=<!--\s*tier:|$)", re.S)

def check_doc(path: Path) -> dict:
    text = path.read_text()
    if not TIER_RE.findall(text):
        sys.exit(f"FAIL: {path} has no tier marker — classify it first.")
    for match in SECTION_RE.finditer(text):
        if "owned-by:" not in match.group(1):
            sys.exit(f"FAIL: T3 section without owned-by owner: {path}")
    counts = {t: TIER_RE.findall(text).count(t) for t in ("1", "2", "3")}
    return {t: BUDGET_MIN[t] * counts[t] for t in counts}

if __name__ == "__main__":
    report = {str(p): check_doc(p) for p in Path("docs").rglob("*.md")}
    total = round(sum(v for r in report.values() for v in r.values()), 1)
    print(json.dumps(report, indent=2))
    print(f"Total review budget: {total} minutes")

A minimal CI integration needs one step in your existing pipeline.

- name: Enforce the draft boundary
  run: python tier_gate.py

The ownership check here is deliberately narrow, because it proves that a human is named rather than that a human wrote the text. The tier structure carries the real weight, since it decides how expensive that human attention must be. The script is only the enforcement layer, and the tier definitions stay a team decision for as long as failure costs change.

The review budget in practice

Consider a documentation set of forty pages, with twenty-five pages of API reference, ten pages of tutorials, and five pages of security and compatibility notes. The budget formula yields 12.5 minutes for Tier 1, 50 minutes for Tier 2, and 100 minutes for Tier 3. The full review costs 162.5 minutes, roughly 2.7 hours, and the script surfaces that number before the reviewer opens the first file.

Without the tier gate, a reviewer facing the same forty pages cannot reliably separate the citation from the compatibility promise, and teams usually drift toward one of two habits. Exhaustive readers spend the full 2.7 hours on every page regardless of its tier, while skimmers spend a fraction of that amount on pages that deserve the most attention. The budget converts an argument about review quality into a number that can be compared with the calendar.

Limitations and who should not use this

The tier markers are only as honest as the author who places them, and a model that is not instructed correctly can copy an owned-by: line into a Tier 3 stub and fool the script. Validate the owner against a MAINTAINERS file or the repository's contributor list before treating the gate as authoritative. The initial tier assignment is subjective, so plan to reclassify sections during the first two cycles while failure costs become visible.

Teams producing audit-mandated or safety-critical documentation should not use this workflow, because those contexts require fully human-authored records rather than graded delegation. Teams whose examples have no executable or lintable ground truth should also wait, since Tier 1 mechanical checks become fiction without a codebase to check against. The workflow is strongest where the failure cost of a section can be observed, measured, and then translated into a review budget.

Start with the tier markers only, keep the script read-only for a week, and compare its predicted budget with your actual calendar. The boundary between machine drafting and human ownership should be a measurement, not a slogan.