Skip to content

refactor(content): retire the experiments type and rework the entry graph - #15

Merged
jamierthompson merged 5 commits into
mainfrom
docs/prose-polish
Aug 10, 2026
Merged

jamierthompson merged 5 commits into
mainfrom
docs/prose-polish

Conversation

@jamierthompson

@jamierthompson jamierthompson commented Aug 10, 2026 •

Copy link
Copy Markdown
Owner

What changed

The site had three content types. It now has two.

experiments was chosen before any content existed, to serve a promise the site no longer makes — that everything here arrives with proof. Its collection, schema, and routes are gone; its two entries are essays. Alongside that, the way entries introduce and link each other was reworked, and a set of presentation gaps that only show up on a first public share were closed.

Why

The content model was a hand-picked fixture. Three categories sampled from where the author thought to look, before the space was explored, which then shaped the writing to fit them. Only one of the two entries was ever an experiment: sweeps-vs-fixed-seeds opened by calling itself a worked case and closed with "Three rules", the same shape as the essays. The eval is a real eval, but its 7/7 denominator was never recorded, it ran once per cell, and the author graded his own tool — so it is an essay about an eval.

The schema went with the routes rather than waiting unregistered: a collection over an empty directory warns on every build, and the shape it encoded — hypothesis, status, started, concluded — was built for the retired model. The first real experiment deserves a shape built for what it needs.

Every link outside the hub sat in the furniture. Measured from source: each satellite entry's links fell in its first tenth or last tenth — an orienting sentence at the top, a pointer at the bottom, nothing where a reader actually is. Exactly one link in the corpus sat at the claim it supported, and it was the only edge joining two entries that were not a mechanical pair. Five entries opened with the same sentence word for word, which is what made it read as furniture and get skipped by the reader it existed to orient.

Eight links moved to the sentences that need them; six links pointing at a target their own entry had already linked are gone; every closer that restated a relationship became a bare pointer.

How it was tested

Full gate green on every commit: format:check, astro check (0 errors / 0 warnings / 0 hints), 186 unit tests, 35 Playwright E2E. Each of the five commits builds standalone.

QA log

Six independent review passes ran against this branch. Findings and their resolution:

Redirects for the retired URLs — raised, fixed, then withdrawn. Three /experiments/* URLs were live and listed in the live sitemap, so retiring the collection would 404 them. vercel.json redirects were added — and a reviewer proved they matched none of the three, because Vercel compiles each source to an anchored regex and, with trailingSlash unset, does not normalize the request first. The live URLs all carried a trailing slash. Verified by compiling the config with @vercel/routing-utils, the library Vercel uses. The corrected version covered every form. The redirects were then removed entirely — the site has never been shared and has no inbound links, so this was machinery for a risk that does not exist.

Internal links were unguarded. Nothing in the suite checked that an internal link resolves to a page the build emitted — on a branch deleting routes and rewiring twenty links. e2e/internal-links.spec.ts now reads dist/ once and fails on a dangling href or a wikilink rendered as unwritten. Mutation-tested both ways. A follow-up pass caught that it treated directories as assets, so a slashless link passed for the wrong reason; it now resolves through routes.

A test could not observe this branch's central change. extractInternalLinkTargets's "unknown paths" case used /about/, which the pattern refuses for having no id segment — so it never reached the collection alternation. Narrowing that alternation from three collections to two was invisible to 185 passing tests; widening it to accept any collection also passed. The added case is entry-shaped and two-segment. Mutation-tested: it is the only assertion in 186 that catches a widened pattern.

Two comments described a schema the same branch had deleted, in README.md and src/lib/references.ts. Both removed. A separate audit found three more comments that would rot — a live link count, an enumeration of the collections, a reference to a nonexistent /about/ page — plus two public roadmap pledges in the essays. All cut.

Prose accuracy. A reviewer found the eval's evidence paragraph pointed at "the source repo" with no antecedent, where the nearest candidate was the wrong repository. Fixed, then cut further.

British spelling: zero instances, verified two ways across all content, tests, and config — a ~90-term targeted list and a suffix sweep.

Notes

public/robots.txt is new — the sitemap was generated and advertised to nobody. The favicon was the Astro scaffold logo and is now the site's own mark. Nine of fourteen descriptions ran past the length a search snippet keeps; all now fit. Enforcing that budget in the schema is #14.

The three-type model was chosen before any content existed, to serve a promise
the site no longer makes — that everything here arrives with proof. It was a
hand-picked fixture: categories sampled from where the author thought to look,
which then shaped the writing to fit them.

Only one of the two entries was ever an experiment. `sweeps-vs-fixed-seeds`
opened by calling itself a worked case and closed with "Three rules", the same
shape as the essays; nothing in it was a study anyone designed. The eval is a
real eval, but its `7/7` denominator was never recorded, it ran once per cell,
and the author graded his own tool — so it is an essay about an eval.

The schema goes with the routes rather than waiting unregistered: a collection
over an empty directory warns on every build, and the shape it encoded —
hypothesis, status, started, concluded — was built for the retired model. The
first real experiment deserves a shape built for what it needs.

`LinkedCollection` and the link pattern stop advertising a collection with no
routes, and the suite gains the case that alternation never had: every path it
rejected was rejected on shape, before the collection list was consulted, so
narrowing that list was invisible to 185 passing tests.
Every link outside the hub essay sat in the first tenth or the last tenth of
its entry — an orienting sentence at the top, a pointer at the bottom, nothing
where a reader actually is. One link in the whole corpus was placed at the
claim it supported, and it was the only edge joining two entries that were not
a mechanical pair.

Five entries opened with the same sentence word for word, which is what made
it read as furniture and get skipped by the reader it existed to orient. Each
now opens on its own material with the hub link inside it.

Eight links move to the sentence that needs them; closers that restated a
relationship give way to ones that say what is on the other side; and the six
links pointing at a target their own entry had already linked are gone, since
the reference index dedupes and the second link only cost the reader.

Descriptions are cut to the length a search snippet keeps — nine ran past it,
the worst losing about 60% of its text mid-sentence in a share card, which is
the surface a first public share exercises.
Nothing in the suite checked that an internal link points at a page the build
emitted, which is what a branch deleting routes and rewiring twenty links
needed most. The spec reads dist/ once and fails on a dangling href or a
wikilink rendered as unwritten.

Mutation-tested both ways: repointing a link at a retired route and a wikilink
at a missing note each fail by name.
The scaffold's icon was the Astro logo, so every tab showed the framework's
brand. A favicon renders standalone and cannot inherit currentColor the way
the mark does in page, so the stroke is pinned to the site's text token with a
prefers-color-scheme swap to read on either tab bar.
The sitemap was generated and advertised to nobody: no robots.txt, and no
reference to it in the built HTML.
@vercel

vercel Bot commented Aug 10, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
jamiethompson.dev Ready Ready Preview Aug 10, 2026 8:45pm

@jamierthompson
jamierthompson merged commit 280c07e into main Aug 10, 2026
3 checks passed
@jamierthompson
jamierthompson deleted the docs/prose-polish branch August 10, 2026 20:48

This branch was successfully deployed

1 active deployment
Preview — f48d31df Deployed Aug 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant