Spec-first delivery

A team can ship for months without anyone being able to say where the rules live. Not because people are careless — because the rules were decided in threads, calls and half-remembered corridor answers, and each of those leaves a different copy in a different head. Ask three people how a flow handles an edge case and you get three confident, incompatible answers.

The second half of the same problem is ownership. When a feature belongs to “the team”, nobody is the person who knows.

The shape

One file per feature, in a Git-backed vault — Obsidian over a repo works because it’s plain Markdown: diffable, reviewable, no vendor, and it sits next to the code rather than in some other company’s product.

Every file carries the same six things:

Section	Why it’s there
Goal	What the user can do afterwards that they couldn’t before.
Business logic	The rules, stated once, in the place everyone reads.
Flow	The happy path, start to finish.
Edge cases	The list the implementation is tested against.
Definition of done	So “done” stops being a matter of opinion.
Owner	One name. Not a team, not two people.

The process

1. The spec is written — by whoever has the context.
2. The team reviews it and leaves suggestions. Disagreement lands here, on a document, instead of later, in a pull request, in code someone already wrote.
3. It is approved or rejected against the wider plan. Rejection at this stage costs a paragraph; rejection after implementation costs a week.
4. Approved specs are ordered by priority. A backlog of approved specs is a queue; a backlog of ideas is a mood.
5. One engineer takes it and owns it end to end — builds it, tests it against the edge cases already listed, ships it.

And the rule everything else rests on:

If the logic has to change, the spec changes and is re-approved first. Only then does the code change.

Without that line the vault becomes documentation theatre inside a month — files nobody trusts, because everyone knows the real behaviour drifted away from them. The rule is what keeps the document the source rather than a source.

Why this matters more now than it did two years ago

Because an agent will implement whatever the spec says, quickly.

That inverts where the difficulty sits. Writing the code used to be the slow, careful part, and ambiguity in the requirements got caught by a developer frowning at it on Tuesday. Now ambiguity goes straight into a working implementation of the wrong thing — and it looks finished.

So the spec becomes both the bottleneck and the leverage. Whoever can state a rule precisely, with its edge cases, is doing the engineering; the typing is what gets automated. A team that writes specs well gets compounding returns from AI. A team that doesn’t gets confident code nobody can verify against anything.

Bugs get a short review, not a culprit

A separate, brief session — right after the morning meeting is the natural slot:

• what happened,
• when it happened, and when it was noticed (the gap between those two is usually the real finding),
• how many users it touched,
• why it was possible.

Written to a standard format, one file per incident, so they can be read as a series. The point is that the same class of mistake doesn’t come back — which is only possible if the review is blameless, because the moment it’s about who, people stop volunteering the detail that makes it preventable.

This isn’t a new idea and I’m not pretending it is: it’s postmortem culture from the SRE book, applied to a small team that doesn’t run Google’s infrastructure but makes the same mistakes twice just as easily.

What I expect to go wrong

• Specs rot. The rule above is the only defence, and the rule needs a person who enforces it when someone is in a hurry.
• It turns into ceremony. Six sections are a floor, not a form to fill. A feature whose spec is three sentences and four edge cases has a good spec.
• One owner becomes one silo. Ownership is about accountability, not exclusive access — reviews and pairing still happen, and the bus factor gets watched.
• Urgent fixes fight the rule. There has to be a hotfix path: ship it, then update the spec the same day, not “eventually”. A rule with no exception gets broken quietly, which is worse than an exception written down.

Related: maymun is the same idea applied to a project with one person in it — decisions locked in a document first, code second.

Stub. Whether it survived contact with a deadline goes here.