From clicks
to specs.
The click hides the decision
Formatting a by hand takes a dozen small decisions: the font size, where the title sits, how many decimals, what to leave alone. You make them without noticing, because you see the result straight away.
A sees none of that. It gets your words, and every decision you didn't write down it makes for you. A is those decisions, written before anyone builds.
Tighten the spec
Twelve cards across two pages, all slightly different. You want them to match.
Predict first: you tell an agent "make the cards consistent". How many of the twelve end up the way you meant?
Each clause removes one guess. The last two are easy to forget: which cards are in , and what must not change. Without them the agent either stops short or does too much.
Written so someone can check it
A good spec has : tests a stranger could run without asking you anything. "Looks nicer" can't be checked. "Values at 28 pt" can.
| Vague | Checkable |
|---|---|
| Make the cards consistent | Values 28 pt bold, titles top left, one decimal and the unit after the number |
| Tidy up the page | Every visual on a 16 px grid, no overlaps, nothing moved off the canvas |
| Add a help button | One "i" button per tile, top right, tooltip from the tile's explanation measure |
| Don't break anything | Validator passes, no file outside the report folder changes |
Check: which clause makes the spec checkable?
When the setting is new, show it as well as say it. Set it once by hand in a , and the agent copies exactly how the file records it instead of guessing.
The rule, in one breath
If you can't check it, the agent can't build it. Write the decisions down before the build, as tests someone else could run.
This is a functional spec with the follow-up questions already answered. You've written them before. Now the reader takes every word literally.
Next: where to put the gates.