A Small Diff Is Not a Small Change

Most teams size their caution by the size of the change. A one-file edit gets a quick look; a thousand-line feature gets the careful review. That instinct is usually right, and occasionally dangerous. The amount of risk in a change is set by the authority it touches, not by how many lines it edits.

The problem

We recently handled a change that looked trivial: a small edit to a documentation file and the removal of a stray, accidentally tracked file. By every shallow measure — line count, file count, "is this just docs?" — it was the smallest kind of work there is.

It was not. The documentation in question did not merely describe the product; it described how the delivery process itself worked: which steps were required, where the canonical location for work items lived, which path needed an approval gate and which did not. Those are not cosmetic sentences. They are the rules people and automated workers rely on as operational truth.

The risk was never implementation difficulty. The risk was quietly restating a governance rule incorrectly — narrowing a requirement, widening a shortcut, or leaving a misleading path alive — while everyone treated it as a harmless cleanup.

What actually happened

The real defect was authority drift. The documentation had fallen out of sync with the canonical sources that actually governed behaviour. It implied requirements that were not universal, and it kept a non-canonical location alive through a stray tracked file, leaving two plausible answers to "where does this live?"

The fix was not to make the docs nicer. It was to make them a faithful mirror of the existing implementation, and nothing more:

• Make the guidance route-specific instead of universal — state precisely which path required the approval gate and which did not, rather than implying one rule for all.
• Remove the stray file so there was a single, unambiguous canonical location.
• Change wording only. Introduce no new step, route, gate, or rule.

Verification was scoped to the kind of change, not its size. There was no point running feature tests on a wording change. Instead the checks confirmed the things that could actually go wrong: that each documented claim matched the canonical source, that no second "shadow" path survived the cleanup, that example commands matched the real tooling, and that the change had not widened into behaviour.

The lesson

A small diff is not a small change when the lines you edited describe how the system is governed. Documentation that mirrors process behaviour — required steps, approval gates, canonical locations, which routes are authoritative — is a protocol surface. Editing it carries the same class of risk as editing the process itself, even though it ships as "just docs."

The trap is that the cost signals all point the wrong way. The diff is tiny, the work feels obvious, and review attention drifts elsewhere precisely when the authority risk is highest.

The broader principle

Size your rigor by authority risk, not by change size.

Before treating a change as routine, ask what it has the power to change if it is wrong. A large feature behind a flag may be reversible and low-authority. A two-line edit to the document everyone treats as the source of truth may be neither. Route the careful review, the explicit acceptance criteria, and the targeted verification to wherever the authority actually sits — which is often not where the line count is.

How to apply it

• Map authority before editing. Identify which source is canonical, which documents merely mirror it, and which files are legacy or removal candidates. Edit mirrors to match the source; do not let a mirror invent new truth.
• Write acceptance criteria against the exact stale claims, not a vague "update the docs." Name the specific sentences that are wrong and what correct looks like.
• Add negative criteria. State what must not change: no new step or route, no behaviour change, no quietly broadened or narrowed rule.
• Prove cleanups, don't assert them. If you are removing an ambiguous path, back it with a concrete check — a search that must return empty — rather than a claim that it is gone.
• Verify examples against their real source. Commands, paths, and configuration shown in docs should be checked against the actual tooling before they are published as guidance.

None of this is expensive. It is mostly a decision about where to spend the attention you already have. The mistake is letting a small diff buy a small amount of care, when the lines it touched deserved a lot.