Every PR plants a seed: how this blog gets written

Nearly every post on this blog started life as a small markdown file committed alongside the code it describes — same PR, same branch, same hour the work shipped. We call them seeds. (The exceptions come from the same habit at a different altitude: this morning's not-a-loop essay grew from a design issue written the day before — a capture note that happened to be issue-shaped.) There are 227 of them in the repo as this post merges — the PR shipping this post adds one, as every PR must — and 22 published posts grown out of the pile. This post is about the pipeline between those two numbers, because the pipeline is the reason this blog reads less like a marketing calendar and more like a live feed of what's actually happening in the project.

The rule: capture, don't pitch

The rule is one line in our agent runbooks: every PR drops one blog seed — a file under notes/blog-seeds/ with a concrete hook, a pointer to the source PR, and the trade-off or gotcha worth expanding someday. Not a draft, not a commitment. A capture. The PR template carries a checkbox so it doesn't get forgotten, and since most of our PRs are written by agents, the discipline actually holds — an agent never skips the checklist step because it's tired.

We didn't start here. The first version was "pitch a blog topic after each PR and wait for a human yes" — an approval gate in front of every idea. That design failed in the predictable way: most ideas evaporated while waiting. The fix was to remove the gate entirely. Capture became zero-friction and always-on; promotion into a real post stayed a separate, deliberate decision that happens later, in batch. An idea preserved while the context is fresh costs one file; an idea lost to an approval queue is gone.

There's a small design lesson even in the file layout: one file per seed, never a shared list. Two hundred PRs appending to one SEEDS.md is two hundred merge conflicts; two hundred PRs each adding their own file is zero. Contributor-facing conventions live or die on that kind of detail.

What a seed looks like

A seed leads with a hook, not a topic label — "the TLS 1.3 ClientHello that broke every browser screenshot" beats "a post about proxies." Then the source PR, then the part that makes the eventual post worth reading: the trade-off, the why, the thing that surprised us. Fifteen lines, written in the moment when the person (or agent) who did the work still remembers exactly which wrong theory they believed for twenty minutes.

That last part is the whole value. Engineering war stories decay fast: a week later you remember that you fixed it, not the three dead ends. The seed pins the dead ends to the commit.

The harvest: combine, don't broadcast

Then, every few weeks, someone sits down with the pile and mines it. This is the part that keeps the blog readable, because the naive version — one post per seed — would flood the index with 227 micro-topics. Instead we curate:

• Score everything. The most recent pass had grown to 224 files, more than one context window holds — so four parallel readers each digested a chunk into a scored catalog, top picks, and combinable clusters, and the shortlist came from their reports.
• Combine when it makes sense. Related seeds fold into one stronger post: nine seeds about retiring a dependency become one post about the craft of dependency excision; a design seed and an implementation seed become one story with an arc. A niche seed that could never carry its own page still contributes as raw material.
• Most seeds never become posts. 227 seeds, 22 posts. That ratio is the system working, not failing — capture is cheap precisely so that selection can be ruthless.

Two rules keep the output honest. First, no fabrication: a post is drafted strictly from its seed files and the linked sources, and anything that can't be substantiated gets flagged rather than smoothed over. Our bot reviewer enforces this as a traceability review — the two posts we shipped this morning came back with line-level notes like "this claim is stronger than the issue's hedged phrasing," and we tightened them before merge. Second, check the shelf before you write: on the same pass, one human-approved pick turned out to already be published as a section of an earlier post — the seed pile records what happened, but only the published bodies record what's been told.

Why this matters if you're reading

The usual company blog is written weeks after the fact, by someone who wasn't in the room, sanded until nothing surprising survives. This one is grown from notes taken in the room, the hour the thing shipped, with the numbers and the wrong turns intact — and published days later, not quarters. The 270-PRs post came from a seed capturing an analysis run the same week; the not-a-loop essay came from a design issue filed the same day it was written up.

So if you want to know what's really going on in this project — what we're building, what broke, what we changed our minds about — you don't need to watch the repo. The repo watches itself, one seed per PR, and the blog is where the good parts surface. Subscribe to the feed and you're effectively subscribed to the project.