Four spec standards, one baseline, two different decisions

Two side projects, one developer, an AI assistant on both. You work on them when you can and when you feel like it, for fun. And precisely because it's for fun, you drop everything that's boring: documentation.

Two projects that age differently

The app started as a way to keep track of the things about my cat that the vet asks for at every visit, and the data was already there: notes on recycled A4 sheets torn into quarters, lab results buried in email, reminders, receipts, and so on. The goal was to gather it all in one place. I was the client (or rather, he was), and I had the requirements and the intended result clear from the first minute. When the what is known up front, the job isn't discovering it: it's keeping the documentation consistent with what the software actually does.

The game is an '80s-style arcade game that started as an idea during a break. Since then it's been a constant cycle of adding, changing, cutting, and refining, and I'm still at it whenever there's time. Every time I actually play it, I find something to redo. There's no point at which the what stops moving. The problem isn't keeping a document aligned, it's closing what you open: I've reopened the scoring design so many times I've lost count.

Doing things in your spare time, both to unwind and to keep up with what's coming out, is the whole point of a side project. But sooner or later the question shows up: where did I write down what this software is supposed to do, why did I decide to build it this way, and what guarantees that the spec — assuming one exists — still describes reality? I answered that question two different ways, deliberately. But first I did something I'd never have thought to do without an assistant.

I wrote the same baseline four times

Spoiler: you don't pick a standard in the abstract, you pick it against the risk you have. The right question isn't "which one is best", it's "which one stops me from making the mistake I actually make".

Specification-driven development standards all look alike until you see them applied to a specific project. So I took the app's baseline — the software exactly as it was that day — and had the assistant rewrite it in four of the most widely used formats:

Four complete write-ups of the same content: the functional areas, the requirements, the acceptance criteria, the log of decisions made so far. By hand that would have taken a week of work I'd never have spent on a side project. With the assistant it took less than an afternoon. What came out was more than a comparison table lifted from some blog post: four different renderings of my own project, from which I ruled out the formats that didn't match the way I work. A matter of taste? Maybe, but there it is.

Kiro wasn't a fit because its best feature — the steering files, the always-loaded context — already existed in the repository: it's the instructions file the assistant reads at the start of every session, and in my very first computer science class they taught me to avoid redundancy.

The PRD wasn't a fit because it mediates between product and engineering, and here those two are the same person. It would have been dead weight.

That left Spec Kit and OpenSpec. A single question decided it: what is this project's number one risk?

The app: I picked OpenSpec, because the risk is drift

When the requirements are known from the start, the risk isn't writing the wrong spec. It's writing the right one and finding that three months later it no longer describes the software. From that moment the document isn't useless, it's harmful: you read it and you trust it.

Spec Kit leaves drift to discipline ("when a feature changes the baseline, update the baseline"), but on a side project discipline is the scarcest resource there is. The scarcity isn't down to laziness: you work in slices, and whoever reopens the project after three weeks doesn't remember their own decisions. At work, memory is distributed: your colleagues, the tickets, code review, someone asking you to explain yourself. Here, memory is that document, the only colleague available: drift doesn't make it useless, it makes it a colleague who lies. Any process that demands less discipline wins, all else being equal.

OpenSpec makes discipline unnecessary: the current specs are the truth, and every change is proposed as a delta that merges into the specs when the proposal is archived. There's no step where you can forget to realign the baseline, because realigning the baseline is the closing step.

Two grafts on top of the standard, taken from the formats I ruled out:

• Spec Kit's Constitution Check, which forces every proposal to be measured against the project's real constraints (the on-disk data format, backups, localization) before any code gets written. It's a template section and I copied it into OpenSpec's proposals. Costs nothing;
• the ADR log, architectural decisions in Nygard format, which captures the alternatives that were rejected and the costs that were accepted. A delta tells you what the software does now, an ADR tells you why it doesn't do the other thing: a year from now that's the information that will be missing.

The game: I picked Spec Kit, because the risk is never closing anything

The game has the opposite risk: with no baseline to defend it has no drift to fear, and you can end up opening more than you close, until everything is half done and nothing is finished.

Spec Kit answers that with two constraints I wouldn't have needed on the app. The first is that there's one open milestone at a time: until that one closes, the second front doesn't open, and last night's idea waits its turn written down somewhere. The second is the gates in the specify → plan → tasks cycle, which are places you can't move forward from without having finished what's behind you. Every milestone becomes a mandate that opens, gets executed, and closes. There's one folder per feature, holding the what and why (spec.md), the how (plan.md), the order (tasks.md). The standard's own scaffolding is enough, and nothing else that isn't genuinely needed.

OpenSpec wouldn't have solved the problem, because it evolves a stable baseline through deltas and a stable baseline is exactly what the game doesn't have; there's no document to keep aligned, there's work to close.

Specs get written while you work, not before

Second lesson from computer science class, back in the Middle Ages: the workflow is spec → implementation → testing → release. It's a theory that works when the what stays still, and reality is another matter.

The game's most recent milestone opened with three items, the threshold I'd set myself for opening one at all. The next day there were eleven. Not because I'd planned badly: because I actually played it, on real hardware; the last four form a chain in which each one only became visible once the previous one was fixed. I thinned out a piece of visual clutter that was too dense, and without it you could suddenly see how much the end-of-level boss was demanding; once that was fixed, lives and score no longer meant what they used to mean; once those were fixed, the game turned out to be missing a time limit.

None of those four items could have been in the previous day's spec. They weren't overlooked: they didn't exist yet.

The problem starts when new items arrive: reopening a long spec to add a story with its acceptance scenarios, renumbering the tasks, updating the dependencies, and reflecting the change back in the domain spec takes half an hour of boring work — at eleven on a Sunday night, no less, when the thing you cared about finally works and tomorrow you go to your real job. It's the half hour you always skip. Skip it twice and the document is dead.

This is the point where the assistant does the dirty work for you. It does it without getting bored, in two minutes and on its own, so it gets done; and because it gets done, the document stays alive.

With that, reality goes back to matching the theory: whatever you discover along the way updates the document first, then the code. In the other order it will never happen again.

Requirements, milestones, and the part you don't back-document

Third lesson from computer science class, this time about documentation. This one school didn't teach me, the years of doing the job did: you document what is still open to decision, not what has already been decided.

On the game a good share of the tasks aren't lines of code: they're tuning done by playing, on real hardware, with the build the people who buy the game will see. Hence the rule that holds the whole thing together, and that applies well beyond a video game: a tuning parameter has a value, and that value has to be recorded where it was decided. A number you changed while trying the software and never wrote down is the seed of drift. And parameters are precisely the thing that changes most often, because they're the only part you judge by using, not by reading.

The same criterion, read backwards, applies to projects that already exist: closed milestones don't get back-documented. The game's milestones that were already finished before the new standard came in were moved into a paragraph of the domain spec and don't get a folder of their own, because a spec exists to decide, and there's nothing left to decide about those. Back-documenting is the most elegant way to waste the week the assistant just saved you.

Generated documentation is credible even when it's false

An assisted cycle produces documents at a speed that was unthinkable before: tasks from the spec, issues from the tasks, plus a cross-analysis pass that checks whether spec, plan, and tasks contradict each other. It's the same movement as requirement → test traceability, performed by something that doesn't get bored doing it.

That brings a very real risk: new requirements, instructions, and specs pile up into thousands of lines of documentation that nobody ever reads end to end. Automatically generated documentation is exactly as credible as hand-written documentation and reads better than average: if nothing contradicts it when it lies, it lies convincingly.

I have a small, instructive case from the game. A task called for replicating in a script what the game's code already drew, so that both paths would produce the same image. It was marked done. It wasn't done: the file's history showed a single line. The document was asserting something that was true in the smallest part, and nobody would have noticed until the two versions started drawing different things.

Three rules came out of that, and I keep them on both projects:

1. Every document that asserts a verifiable fact has something that verifies it. That case was closed with a test that compares the two paths on every run of the suite. The document can no longer lie on its own: it has to lie in agreement with the test.
2. Generated documentation is not the source of truth. When two documents disagree, exactly one of them wins, declared in advance.
3. Anything no test can measure gets marked as a judgment call, not as a requirement. The game has an entire milestone built that way: tests, build, and performance numbers all fine, and yet none of those reports can tell you whether "hard" is actually hard. That verdict comes from a pair of hands on real hardware, and the spec says so outright instead of faking a measurable criterion that doesn't exist.

The three rules have one thing in common: none of them asks the assistant to be reliable. They ask it to write. The guarantee comes from somewhere else: a test, a hierarchy declared in advance, a pair of hands on real hardware. The work can be delegated, the responsibility can't.

What the assistant does, and what you don't delegate to it

When it comes to writing specs, the assistant isn't vibecoding's clever colleague, the one suggesting shortcuts. It's the one who keeps the minutes. It decides nothing, it records everything, it remembers the decision that was made and then forgotten, it rereads in full the documents I no longer reread. The value isn't in the intelligence, it's in not getting bored. The minutes aren't for a team that doesn't exist. They're for me when I pick the code back up: I'm the only reader these documents will ever have.

What you can delegate without a second thought: drafting four variants of a format so they can be compared, reopening a spec and slotting in a story that's consistent with the others, spotting the inconsistency between three documents nobody would ever read in parallel.

What you don't delegate: deciding what the project's number one risk is. That's the choice everything else follows from, and in the four folders the assistant wrote, the answer wasn't there.

Worth saying, because mine is the most forgiving case there is: here the document has a single reader, and whoever gets it wrong pays alone. The same tools end up on desks where the spec is read by a team that turns over every few months, or by a client using it to challenge what you delivered. The assistant works the same way everywhere: what changes is how much a wrong line costs. Hence the proportion: the more vital a document is, the less autonomy you give to whoever writes it for you.

Finally, if a side project dies before long then all of this was wasted time: you write the code and that's that. The dividing line is the first real break, the one you come back from remembering nothing. If the project survives it, the afternoon spent choosing a process isn't time taken away from the project: it's exactly the time the project gives back to you when you reopen it.