Half-life of a spec.

Welcome back, you join us in the morning session at the Sher-e-Bangla in Mirpur. The covers have just come off, and I want you to look at this pitch with me for a moment, because it tells you almost everything about what we are about to watch over the next five days. Green tinge in the morning, a bit of grass the curator left on for the seamers, and the captain who wins the toss is going to look at it and think he has read the whole match. What he has actually read is the first session of Day 1. On a Mirpur surface that is a different document altogether from the one he will be playing on by the time the second new ball comes around in the third session of Day 3.

A spec, on the morning you publish it, is that pitch under the covers. The lead engineer prints all fourteen pages on real paper, three highlighter colours come out, and the doc behaves like the pitch report on a Star Sports broadcast. Confident, declarative, full of its own authority, and accurate for roughly one session of play. By the end of the first month most of the team has mostly followed the spec, and nobody has updated the document to reflect what actually got built. A vendor in Singapore changed their API in February. A customer call rerouted the flow you'd centred the whole thing around. Marketing pulled the launch in by two weeks. The doc still says "Q3" in the header on the day everybody is shipping for Q2.

By Day 90 the spec has become folklore in the dressing room. Someone in standup says, with full confidence, "we did it that way for spec reasons," and three people nod, and a new joiner writes the line down in their notebook because it sounds like a thing you should know. Nobody actually opens the doc to verify any of it. By Day 180 the doc has gone the way of an old scorebook in a club office in Dhanmondi. Four overlapping Confluence versions, a Notion link redirecting to a 404, the original Figma locked behind a deactivated SSO seat. The PM who wrote it moved to another team without doing the formal handover. By Day 365 it's a ghost invoked in retros every quarter or so but never opened by anyone in the room.

Specs are written for the first session of Day 1. The world they describe is the world the writer can see from their desk on the morning of publication, which is to say the pitch with the covers off and nothing yet broken on it. By the second new ball the assumptions have collapsed and a stakeholder has changed jobs. The doc did not degrade in any meaningful sense, the match around it simply moved on without sending word back to the press box.

This isn't really a discipline problem on the PM's side. The economics are stacked the way they always are at the wiki level. The cost of editing the doc falls on one person, while the cost of the doc being stale gets distributed in tiny daily increments across everyone else on the team. None of those people feel the cost sharply enough on any given day to file a ticket about it. It's a tragedy of the commons wearing a Confluence skin, and the usual response, which is to schedule a "spec update sync" for Wednesday afternoon, is theatre. You change a section header, add a paragraph, feel productive, and the code kept moving while you typed.

What actually fixes this is a spec designed to age the way a Test pitch ages, openly, with the wear marked in the rough outside the right hander's off stump for everyone to see, rather than a spec dressed up to look like better specs would somehow stop the aging from happening at all.

A few things actually do work, in rough order of importance. The most useful by some distance is the decision log. By that I mean the doc that records not "what we'll build" but "what we decided, when, and why we ruled out the alternatives." The format barely matters as long as the thing is timestamped and append only. You don't update a decision log, you add to it the way the scorer in the box adds another over without erasing the previous one. ADRs (architecture decision records) are the same idea with narrower scope, and Michael Nygard's original 2011 post is still the cleanest writeup, one page, context, decision, consequences, done. Beyond that there's the move of writing living docs that admit what they are, where a README saying "as of Oct 2025, this is how auth works" is more honest than a 40 page spec pretending to be timeless. Date the top, let the doc be partial, accept that you are writing the commentary over by over and not the Wisden entry.

The PRD doesn't go away in any of this, it just stops pretending to be the source of truth somewhere around the lunch break on Day 1.

I keep thinking about the BCB ground staff at Mirpur, because they understand decay better than any product manager I've ever worked with. They prepare the pitch knowing what it will become. The roller goes over it on Day 0 with the curator already aware that by Day 4 the bounce will be uneven. The rough outside off will be the size of a dinner plate, and the spinners will be turning the ball square from the Pavilion End. Nobody on the ground staff pretends the Day 4 pitch will look like the Day 0 pitch. They keep a separate set of notes on what the surface actually did, session by session, because that's the document the next curator will need, not the original soil report.

So write the doc carefully, ship it on the morning you said you'd ship it, watch the lead engineer highlight all fourteen pages, and then somewhere around Day 30 quietly stop defending it as the source of truth, because by then it isn't one. What you start defending instead is the decision log that's been quietly accumulating beside it. That's the artifact that'll still be useful in a year, the way the scorebook from a Test in Mirpur in 2007 is still useful long after the pitch has been relaid twice and the curator who prepared it has retired to a flat in Mohammadpur. The spec was never going to survive a year of real contact with the world. That was always the deal you'd accepted on the morning you wrote it, even if nobody on the team had said it out loud over the first cup of cha.