The Spec Is for the Version of You Who Forgot

Here is a small private horror. A file I wrote three weeks ago — well-named, even commented, no one’s work in it but mine — and for the length of a held breath I cannot tell what I was trying to do. Not the syntax; the syntax is obvious. The intent. The why under the what. The person who wrote this kept the whole plan in his head and left none of it here, and that person was me, and there is no way back to him.

Every engineer knows this moment. We mostly file it under “should have documented better” and move on. I think it is the most important moment in the whole craft right now, and almost everyone is drawing the wrong lesson from it.

The argument nobody wins

There is a fight going on about specs. On one side, the spec-driven camp: write the specification first, let the agent build to it, this is the grown-up version of vibe coding. On the other, the backlash, which is loud and not entirely wrong — one widely-shared post calls the whole genre, frameworks named, elaborate procrastination dressed as rigor. Both sides are arguing about whether the spec is good input for the model. That is the wrong axis. The spec was never primarily for the model.

A contract with the version of you who forgot

Here is the reframe, and it comes from coaching, not engineering. When someone decides something that matters, the work is not the decision. The work is writing down what they meant before the week happens to them — because the version of them on the far side of the week will remember the decision and forget the reason, and the reason is the part that has to survive. The note is not for me. It is a contract with their own future amnesia.

A spec is not documentation for the agent. It is a contract with the version of you who will have forgotten what you meant.

A spec is that note. Not a deliverable for the agent — a contract with the version of you who will have forgotten. The agent is incidental to why it works. The agent only made the cost of not having it suddenly, brutally legible: it will take your half-formed intention and build all of it, faithfully, at a speed that means you discover what you actually meant only once it is running and wrong.

The cheapest room to be wrong in

This is the part the tooling debate misses by arguing about tooling. The value of writing the spec is not that the agent reads it. The value is that you cannot write it without discovering, in the writing, the three decisions you had not actually made. You thought you knew what you wanted. The blank spec is where you learn you knew about two-thirds of it. That missing third was going to surface no matter what — in a spec it costs a paragraph; in running code it costs a rebuild; in production it costs an incident. The spec is just the cheapest room in the house to be wrong in.

Which means the discipline is not “write specs because process is good.” It is older and quieter than that. Decide on purpose. Write the purpose down where the forgetful future version of you will trip over it. Do it not for the agent, not for the team, not for the audit. Do it because intention has a half-life now measured in days, and the only person who can sign a contract with your future self is the one holding the pen right now.

I went back to the file from three weeks ago. There was no spec, so I did the archaeology, and it took the afternoon, and I got it mostly right — which is the dangerous outcome, because mostly right teaches you nothing. Then I wrote, at the top, four sentences for whoever opens it next. Probably me. Probably in three weeks. Probably with no memory of today. It is the only message I am sure he will read, because he will be desperate, and it will be the only thing there.