The release plan went stale the same day it was written

Type

Bug — in a document, measured the same way code is

Found while

SAPE-2

Triage

—

Status

Done

Version

1.0.0

Severity

Low as a defect; the reason it is written up is the lesson

Description

The 1.0.0 release plan has a section called "four decisions that cannot be taken back" — the part a release plan exists to catch. Two of its four subsections were wrong when somebody went back and measured them, and both were wrong in the place the document itself calls most important.

• §2.1 presented pager.Magic still spelling the old name as an open decision, to be settled before the tag. It had already been settled and shipped.
• §2.2 conflated two different things: const Format uint16 = 1 (pager.go:63), a field of its own, with the trailing 0, 1 of the eight-byte Magic array. It also recorded "there is no such rule and no measurement of that refusal path", which is half right — the refusal exists and is shipped; only the measurement is missing.

Both are corrected in place, in the subsections themselves, not gathered into a footnote.

Evidence

Timeline, from commit timestamps rather than from either document's own account:

Thirty-one minutes. That is how long §2.1 described the code.

One detail the correction itself gets slightly wrong, and it makes the lesson sharper rather than weaker. The correction says the plan also "had the line number wrong". It did not, when it was written: at 6cb845a^, var Magic really was at pager.go:50 and const Format at pager.go:52. The same commit that changed the value moved the declaration to 61 and 63. So the line number was not an error of care — it went stale at exactly the same instant, and by exactly the same mechanism, as the claim it decorated.

Verified independently, at the tree as it stands today:

internal/pager/pager.go:61  var Magic = [8]byte{'S','A','P','E','D','B', 0, 1}
internal/pager/pager.go:63  const Format uint16 = 1

Triage

Not triaged by the usual question, because it was fixed as it was found: the correction landed in ed69061, three hours after the plan and three hours before anybody made a decision on it.

Had it needed triage the answer would have been yes anyway, on the second clause. The plan is what the four irreversible decisions get made from. A document that presents a settled decision as open invites somebody to re-decide it, and a document that confuses a version field with two bytes of a magic array invites a version-bump rule written against the wrong field — which is a compatibility surface, frozen at the tag.

What it cost, and the lesson worth keeping

• A planning document is a measurable claim, and it goes stale exactly as fast as the code changes. Not faster, not slower: this one had a half-life of thirty-one minutes because that is when the code moved.
• The two errors are different species, and only one is about speed. §2.1 was correct and decayed. §2.2 was never correct — nothing changed underneath it; somebody read a byte array as a version field. Freshness discipline catches the first. Only re-measuring catches the second.
• The countermeasure that would have caught both is the same one the tickets use: cite a file and a line, and re-run the citation before acting on the paragraph. A claim with a file:line on it can be checked in seconds; a claim without one cannot be checked at all.
• The corollary applied to this page: every number here was re-measured against the tree, and this sentence is the part of the page that will go stale first.