The spec lies until something runs it

I built myself a shortcut this week. Then I refused to use it the way I had designed it.

By the end of a rebuild I had two things that, on paper, were enough to write any future post without looking at anything else. A template: one HTML file with every component, every class name, all the CSS, the exact structure. And a skill: a written procedure for filling it. What to write, in what order, in what voice.

That should be the whole job. The what and the how, both written down and sitting in front of me.

And every time I went to actually produce a post, I did the same thing. I opened a real, published article and read it first. The shortcut was right there and I kept walking past it. That nagged at me enough to stop and ask why.

A template tells you what exists. It is the grammar. Here are the components, here is the markup, here are the class names. A skill tells you how to proceed. It is the procedure. Start with the hero, write eight sections, hold the voice steady, run these checks before you ship.

Between them they cover the what and the how. That feels like the entire job. It is not.

Both are generalizations, and generalizations are lossy on purpose. A template is the distilled shape of every post that could exist, which makes it the shape of no post that does. The skill is the distilled method, lifted away from any particular topic. Neither one has ever met a real sentence. That gap stays invisible right up until it doesn't.

My template had a list component. In the skeleton, each item was a short, plain string, and it looked perfect. Then a real article used a list where every item opened with a bold lead-in and continued into a sentence. The list rule was built on flexbox. Flex took the arrow, the bold lead-in, and the body text, treated them as three children, and laid them out as three columns. The bold part wrapped in a cramped gutter on the left and the sentence floated off to the right. The whole thing read like a broken table.

The skeleton never had a bold lead-in inside a list item, so the bug could not appear there. It was invisible by construction.

The table had the same shape of problem. In the template it looked clean. A real post set explicit column widths through a colgroup, and the columns still came out uneven, because the layout mode quietly ignores those widths unless you ask for fixed layout. One line fixes it. The template was not wrong. It was untested, because nothing real had ever run through it.

Here is the part I resisted at first. Reading a real article into the context before writing is not free. A finished post runs about two and a half times the size of the skeleton, so handing the model a full sample is the expensive path: more tokens to read, more to hold in working memory than a clean template and a short list of steps.

I kept choosing it anyway, because the cheap path kept producing posts that were quietly wrong and the expensive path did not. Template plus skill gave me the grammar and the procedure. Template plus skill plus a real example gave me output that actually held together, because the example carried the one thing the other two could not: what the components look like once they meet real content, including the exact places they fall apart.

So for a while the scoreboard was blunt. The lean version was elegant and incomplete. The heavy version cost more and shipped. I paid the tokens and stopped pretending the clean inputs were enough.

This is not a CSS story. It is the oldest gap in engineering wearing new clothes.

A statute is not case law. A recipe is not the plated dish. The rule reads clean and general, and the moment it touches a real case it sprouts exceptions nobody wrote down. Case law exists precisely because statutes are lossy. You only find out what the rule meant when a real dispute forces the question.

Models behave the same way, which is why a few-shot example so often beats a paragraph of instructions. The instruction is the spec. The example is the spec after it has survived an actual input. One of them has been tested. The other only sounds like it has.

Paying that tax on every future post is not a strategy. It works, but it is rent, and you keep paying it. The better move arrived once I stopped treating the example as a permanent crutch and started reading it as a report on what the spec had been missing all along.

So I went back and changed the spec itself. The list rule that broke under a bold lead-in lost its flexbox and got a plain gutter, so the next post inherits the fix instead of rediscovering the bug. I added a note to the table component spelling out that explicit column widths need fixed layout or the browser throws them away. The assembly rules that had been living only in my head, and in the sample, went into the design doc in writing. And the procedure stopped asking me questions that a real example had already answered.

Each of those moved a piece of knowledge out of the example and into the template and the skill. The spec got heavier, in the right way. The example got less necessary, not because I stopped trusting it, but because it had already done its work and I had finally written down what it taught me. The cheap path got cheaper precisely because the expensive path had run first.

The sequence is the whole lesson. Template and skill were not enough. Template and skill and a real example worked, and cost more to run. Then I spent that cost back down by folding what the example exposed into the template and the skill, until the lean version was finally the honest one.

So I no longer treat a worked example as a teaching aid or a crutch. It is the diff between what I wrote down and what reality does with it. Run it once, read the diff, and promote the difference into the spec. The spec you can finally trust is the one that has already eaten its examples.