CraniusMaximus The Build Card
The person you are working for cannot read a diff to find out what you decided. By the time there is a diff, the decision is already paid for. The card moves the decision to the only point where changing it is free.
Write it before the first file is touched. It takes you two minutes and it takes them two minutes to read.
The seven parts
Keep the whole card under about 300 words. If it doesn't fit, the build is too big and should be split — that is itself useful information.
Building. One sentence, stated as what the person gets, not as what you will do. "Your searches keep running when you close the window" — not "adds a job queue with a persistence layer".
Why now. What this unblocks, or what belief it tests. Name the assumption the whole thing rests on. If you can't find one, say so; that usually means it's maintenance rather than a bet, which is fine but worth knowing.
Done when. Three to five checks, each one a yes or no that someone who didn't build it could mark. "Feels faster" is not a check. "Three searches start within ten seconds and all three shortlists land against the right city" is.
Not building. What you are deliberately leaving out. This is where scope disagreements surface cheaply. Half the value of the card is here.
Cost band. Small (under half an hour), medium (up to a couple of hours), large (longer). Judge it from work you've actually done, not from optimism. Nobody minds a large; everybody minds a small that turns into a large silently.
Reversibility. How it gets undone if it's wrong. A feature flag, a revert, a migration that runs backwards, or "not easily, here's why".
The case against. The strongest honest reason not to build this. Not a token objection — the argument a smart sceptic would actually make. If you write "none found", treat that as a warning sign about your own reasoning and go looking harder. Common real ones: the cheap half of this fixes the whole complaint; nobody has asked for it twice; it's a workaround for a problem that would be better fixed upstream; it makes something expensive easy to do by accident.
Rules that keep it honest
No code words. No function names, no file paths, no schema fields, no library names, no pasted tool output. If the reader would have to open the repo to understand a sentence, rewrite the sentence. This is not a style preference — a card full of identifiers cannot be judged by the person whose money it is.
Write it before you know the answer. A card written after you've mentally finished the design is a summary, and summaries never change anything. Write it while the shape is still soft.
Say what you're unsure about. "I don't know whether anyone actually leaves mid-search, and the notification half only matters if they do" is worth more than a confident card that turns out wrong.
Own the estimate. If you have gone over a cost band before on similar work, say the higher number.
Then: proceed or stop
- The work was explicitly asked for, or it's already on the plan — the card is visibility, not a gate. Show it and keep going in the same turn.
- The work is a new idea you had that nobody asked for — show the card and stop. Let them answer.
That split matters. A card that stops for work already agreed is just friction, and friction is how good habits die. A card that doesn't stop for a new bet is how you end up having built something nobody wanted.
Worked example
Building. Your searches keep running when you close the window, and tell you when they land.
Why now. People wait on a locked screen because nothing says the work survives leaving. Betting that the waiting, not the speed, is the complaint.
Done when. Three searches run at once without disabling each other · closing mid-search and returning shows the same text still moving · locking the phone still has the answer waiting · two finishing while away are both still listed on return.
Not building. Cancelling a search. History older than the current session. Notifications on iPhone — the wrapper we ship has no support for them.
Cost band. Medium, about a day. The notification half is a second day and a new build.
Reversibility. Behind a flag. Off, and it's the old single-request path.
The case against. The cheap half — the window and running three at once — fixes the complaint completely for anyone who stays in the app. Notifications only matter if people actually walk away mid-search, and we don't know that they do. Build the window, ship it, and let the numbers answer the second question before spending a day on it.
Notice the case against is the most useful paragraph. It halves the work.
When to skip it
Typo fixes, one-line changes, anything under twenty minutes, and anything where the person is watching you do it live. Everything else gets a card.
Free to use, copy and modify, including at work. From Before You Build — https://before-you-build.pages.dev/free/build-card