Source-Bound Docs: Models Restate Files, Humans Own Promises

Model-drafted documentation is only useful when every claim generated by the model can be traced back to a file that already exists in the repository. Sentences that lack a source become unofficial contracts, and these contracts are costly to undo after they have been published. The key distinction is clear: models are allowed to restate facts that have been checked into the repository, while humans are responsible for promises, versions, and any unsupported advice.

This article explains a cite-or-drop pipeline that enforces this separation before the draft is submitted as a pull request. Restating facts is relatively inexpensive, but promising something is not.

Even with a heading labeled as a draft, the model retains the ability to invent numbers, support windows, and compatibility language. A table copied from an OpenAPI specification represents a restatement; however, a sentence that calls an endpoint as production-stable is considered a promise. Reviewers who merely skim markdown differences often fail to notice these second-class promises, as they appear to be routine explanatory text.

Linking each sentence to a specific path, symbol, or ADR identifier makes the missing source visible during continuous integration. The costly mistake is not the use of ornate language, but rather publishing a "getting-started" page that transforms a beta feature into a supported contract. Support teams then inherit a sentence that nobody signed, leading to additional rework after customers have already quoted the line.

A source-bound pipeline treats such a sentence as a build failure rather than a style comment on the pull request. Although heading labels remain useful for navigation, they cannot detect a promise that exists within an otherwise draftable section. A decision table for draft rights should be treated as a checked-in policy, rather than a mere vibe check applied by reviewers after the model has already written the content.

The table lists documentation surfaces on the rows, and separates restatable facts from commitments that require a human owner on the columns. If a proposed sentence cannot be linked to a row and a column, it should not be included in a model-touched markdown file. While the model can still draft content, humans must own any promises or unsupported claims.

Restatements still allow the model to generate numbers, support windows, and compatibility language. A table copied from OpenAPI specifications is considered a restatement, whereas a sentence that mentions an endpoint as production-stable is considered a promise. Reviewers who skim markdown diffs may miss these second-class promises, as they blend in with ordinary explanatory prose.

By binding each sentence to a path, symbol, or ADR identifier, any missing source becomes apparent during continuous integration. The financial consequences of this mistake are not merely poor prose; they include upgrading a beta feature into a supported contract without the necessary human validation. Support teams end up inheriting a sentence they did not sign off on, resulting in additional work after customers have already quoted the line.

A source-bound pipeline considers that sentence as a build failure instead of a stylistic comment on the pull request. The table remains useful for navigation purposes, yet it cannot identify a promise that resides inside an otherwise draftable section. A decision table for draft rights should be used as a checked-in policy, rather than a subjective vibe check applied by reviewers after the model has already generated the content.

Rows in the table represent documentation surfaces, and columns differentiate restatable facts from commitments that require a human owner. If a proposed sentence cannot be linked to a row and column, it should not be included in a model-touched markdown file. Even though the model can still draft content, humans must own any promises or unsupported claims.

Restatements allow the model to generate numbers, support windows, and compatibility language. A table copied from OpenAPI specifications is considered a restatement, while a sentence that claims an endpoint as production-stable is considered a promise. Reviewers who skim markdown differences may overlook these second-class promises, as they blend in with regular explanatory prose.

By binding each sentence to a path, symbol, or ADR identifier, the missing source becomes visible during continuous integration. The financial impact of this mistake is not limited to poor writing; it includes transforming a beta feature into a supported contract without the necessary human validation. Support teams end up inheriting a sentence they did not approve of, leading to additional work after customers have already quoted the line.

The source-bound pipeline treats this sentence as a build failure rather than a stylistic comment on the pull request. The workflow consists of four stages that run sequentially and fail when a claim cannot be bound. First, the system inventories the source artifacts that are allowed to justify prose in any model-touched file. Second, it extracts candidate claims from the model draft as structured records instead of just scoring raw markdown.

Third, each record is bound to a specific source path; and fourth, the pull request is rejected if any unbound claims remain. The following sections describe the implementation as a proposed workflow rather than a report of actual production results. Commands, fixtures, and tests are labeled as unexecuted examples and require local adaptation before enforcement.

Keep generated pages under a separate directory so human-owned documents never share a glob pattern with model output.