# Build Card

> Use BEFORE starting any build that would take more than about twenty minutes — a new feature, a redesign, a refactor with a visible result, a new automation. Writes a short plain-English card the human reads before any code exists, then waits or proceeds according to the rule at the end. Also invocable directly as /build-card to think through work without building it.

- Skill: `craniusmaximus/build-card` (Agent Skill)
- Install (CLI): `npx skillmds@latest add craniusmaximus/build-card`
- Raw SKILL.md: https://api.skillmd.com/api/skills/craniusmaximus/build-card/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: CraniusMaximus (https://skillmd.com/u/craniusmaximus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/craniusmaximus/build-card

---


# 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