site: give every blog post one narrative spine

[AkashGoenka]

Structural editing pass over all ten posts in site-astro/src/content/blog/. The voice was already right — first-person, skeptical, candid about mistakes. The problem was that the essays alternated between personal essay, teardown, methodology memo and product argument, several opened abstractly and only reached their evidence halfway down, and several ended on a checklist or a feature summary instead of a conclusion.

Every post now runs on the same spine — concrete observation or incident, the tempting reading, the mechanism that complicates it, the general principle, then what coldstart does and doesn't claim — without flattening the different essay types into one template. No claims were softened, no caveats dropped, and nothing was rewritten into marketing copy.

Two real defects found on the way

Arithmetic. why-most-token-savings-tools-lie described the JMRI correction from 39% to 31% as "fifteen points lower". It is eight. The wrong number appeared in four places: the prose, the SVG <desc>, an in-figure label, and the figcaption. All corrected.

A citation with nothing behind it. The same post cited where-the-tokens-go as the source of the "~90% cache reads, ~2% tool output, ~25k fixed base across 15 turns" decomposition — but that post never stated those figures. That is also why it opened abstractly: its own evidence had been published in the neighbouring post. The decomposition now opens where-the-tokens-go, and the savings post keeps a compressed reference.

A duplicated standfirst. notes-should-be-written-by-whoever-read-the-code repeated its lead frontmatter verbatim as its first body paragraph. BlogPostLayout already renders lead above the body, so readers saw it twice.

Per post

Post	Change
where-the-tokens-go	Opens on the decomposed session; "Measuring your own" finished out with real mechanics; new close separating what one session proves from what it doesn't. 7→8 min.
an-index-cannot-answer-twice	Defensive visualisation section dissolved into the evaluation paragraph (steps-not-tokens metric kept); headings name arguments; ending moved off product exposition onto the principle.
the-tool-the-agent-doesnt-call	Hook incident moved ahead of the taxonomy it justifies; explicit design rule added to the closing section.
from-four-tools-to-two	Deletion numbering dropped (it jumped one→three→five); headings name what was removed; fixed a "the third removal" mislabel.
notes-should-be-written-…	Standfirst de-duplicated; generic headings replaced; product section cut so the essay ends on the rule. wordCount 1086→1128.
codebase-memory-is-not-agent-memory	Claimed a design mistake but never showed one. Now opens on the real one: aliases that unioned forever left notes keyed on "capture never fires" long after that regression was fixed — the identity/incident split. Section overlapping the notes essay reduced to a link. 6→7 min.
why-coldstart-makes-zero-llm-calls	Opens on literal questions from real sessions; the "where coldstart loses" boundary moved ahead of the tradeoff argument; promotional heading replaced.
what-a-graph-cannot-see	New closing section: the missing edge didn't exist in the source, it was created by an incident. Ends on the general rule.
why-most-token-savings-tools-lie	Opens on the number almost published; caveats moved up next to the numbers; repetitive close replaced with the principle that a saving is a property of tool × codebase × task.
how-your-own-benchmark-lies-to-you-first	Opens on 2,136 / 2,131 / 2,135; imperative headings replaced with ones naming each incident; checklist reframed as residue.

Verification

• npm run build passes, 24 pages.
• All ten posts have complete, valid frontmatter.
• The hand-maintained circular next chain still forms exactly one closed loop covering all ten posts.
• Every SVG figure intact (9 posts have one; the-tool-the-agent-doesnt-call never did).
• All four internal links resolve against built pages.
• Every number and caveat preserved: Arches 64% / recall two points better, JMRI 31% / recall at parity, navigation-only scope, one run per arm.
• One post rendered in a browser to confirm layout and figure.

Not done

Left the title why-most-token-savings-tools-lie alone. It is more accusatory than the argument, which is mostly that these numbers measure a different thing — but renaming it changes the slug and breaks the next chain plus the inbound link from the benchmark post. The body now says plainly that most such numbers aren't dishonest. Happy to do the rename and chain surgery as a follow-up.

Based off main rather than site/design-language-v2, since the blog markdown is byte-identical on both and this shouldn't queue behind the unmerged design revamp.

🤖 Generated with Claude Code