The one-page brief that saves a month of building
Before any code, we write one page. It is the cheapest month of rework you will ever avoid.
The most expensive bugs in software are not in the code. They are in the understanding: the feature built for a user who does not exist, the edge case nobody mentioned, the success metric decided after launch. A short written brief catches most of them before they cost anything.
It fits on one page on purpose. A brief that is long enough to need a table of contents will not be read, and a brief nobody reads protects nobody.
What goes on the page
1. The problem, in the user's words
One or two sentences describing what is hard for whom today. Not the solution. If you find yourself writing "users need a dashboard", rewrite it as what the user is trying to do and why they cannot.
2. Who it is for, and who it is not for
Naming who is out of scope is as useful as naming who is in. It stops a first version from trying to serve everyone.
3. What done looks like
The observable change after launch: a task that takes minutes instead of hours, a drop in support requests, a number of people completing a flow. Pick one measure you will actually check. For AI features, define it around the decision the feature improves.
4. Constraints
Deadlines, budget, platforms, regulations, data you can and cannot use, and the phones and connections your users actually have. Constraints are not obstacles to list at the end; they shape the design from the start.
5. Open questions
What you do not know yet, and who will find out. A brief with no open questions is usually a brief that has not been thought through.
Writing it down is not paperwork. It is the fastest way to discover you disagree.
How to use it
Share the page with everyone who will build, approve or support the feature, and ask them to mark what is wrong, not what is nice. Most disagreements surface within a day. Resolve them on the page, then build. When scope questions come up mid-project, the page is where you check, and where you record the change.
Template: Problem · For whom (and not) · Done looks like · Constraints · Open questions. Five headings, one page, written before the first commit.
Start with the decision, not the model
Most AI projects that stall were never wrong about the model. They were vague about the decision the model was meant to improve. How to start from the decision, with a worked example.
Retrieval before fine-tuning: making an LLM answer from your own documents
If you want a language model to answer from your company's documents, start with retrieval, not training. A worked example, from the first document to the first honest measurement.
Test your AI feature like you would test a payments flow
Nobody ships a payments change because it looked fine in a demo. AI features deserve the same discipline. A worked example of building an evaluation suite your team will actually use.
Build for the network your users actually have
Your office Wi-Fi is not your user's connection. Designing for real phones and paid-for data changes what good engineering looks like.