The Problem Behind the Request
Your operations lead writes one line to an agent: "Keep the store app in sync with the warehouse system." Twenty minutes later the agent hands back a plan. It has a webhook listener, a change-data-capture pipeline, a conflict-resolution strategy for when a store and the warehouse edit the same count, and a retry queue. The plan is coherent. Each piece is justified by the piece before it. It would take three weeks.
Then you ask the operations lead one question: "What goes wrong today?" The answer is that store managers open at 07:00, they have to send reorders to the warehouse by 08:00, and the stock report they rely on arrives by email at 09:00. That is the whole problem. The warehouse system recounts stock once a night, at 02:00, so no data exists that is fresher than 02:00. A real-time sync engine would copy a number that changes once a day, in real time.
The agent did what it was told. The request described a solution, and the agent built that solution at full size. The question that saved three weeks was about the problem, and it had to be asked before anyone looked at a design.
A request is someone's guess at a solution
When a person asks for software, they have usually already done a round of design in their head. They felt a pain, imagined a fix, and then described the fix. "Add export." "Sync with the warehouse." "Add a login." The words you receive are the output of their design step, and the pain that started it has been left behind.

A human colleague often recovers the pain by instinct. They ask "why?" or they know the business well enough to guess. A coding agent works from the text it was given. If the text says "sync", the agent reads it as continuous updates, because nothing in the brief says how fresh the data has to be. The agent is filling the gap between your words and a finished system with the typical case, and your case may not be typical.
There is a name for the general version of this: the XY problem. Someone wants X, decides Y will get them there, and asks for help with Y. The fix is the same for people and agents: before judging a solution, go back and find X.
Who has the problem, and in what situation
Start with a person, a task and a moment. "Users" is too wide to design for. In the warehouse case the person is a store manager, the task is deciding what to reorder, and the moment is the hour between opening and the 08:00 cutoff.

That moment carries most of the design information. It tells you the data has to be ready before 07:00. It tells you the counts at 14:00 yesterday do not matter, because no reorder decision is made at 14:00.
Clayton Christensen's jobs-to-be-done work frames this as the progress a person is trying to make in a particular circumstance, and the circumstance is the part that briefs usually drop.
Once you have the job, look for what the person does today. Here it is a spreadsheet that someone in the warehouse office exports after arriving at work and emails at 09:00. Every new feature replaces some existing tool or process, even if that process is "they guess" or "they phone someone". Naming it matters for two reasons. It shows you the minimum bar your solution has to clear, and it shows you why anyone would switch. The store managers will switch to anything that gives them the same numbers before 07:00, because that is the one thing the spreadsheet fails at.
State the outcome as a change in the world
A feature is something the software has. An outcome is something that is different for a person after the software exists. "The app syncs with the warehouse" is a feature. "Every store manager can see last night's counts before 07:00, and reorders stop missing the 08:00 cutoff" is an outcome.
Above the outcome sits the purpose, the reason the work exists at all. The stores reorder so the shelves hold what customers come in for, and a late reorder leaves a gap on a shelf for a day. The purpose is a test for the outcome: if a solution could meet the outcome while the shelves got emptier, the outcome is wrong.
Outcomes are useful because you can compare solutions against them. Put numbers in if you can find them. Suppose the operations lead tells you that across 12 stores, about 15 reorders a week miss the cutoff and go out a day late. Now you have a measure: late reorders per week, from about 15 to close to zero. Here is how three candidate solutions look against it.
| Option | Freshness of data | Work to build | Meets the outcome |
|---|---|---|---|
| Real-time sync engine | As fresh as the source, which is 02:00 | About three weeks | Yes |
| Nightly import at 03:00 | 02:00 | About a day | Yes |
| Move the spreadsheet email to 06:00 | 02:00 | A change to one person's routine, or a scheduled export | Yes, if the export can be scheduled |
All three meet the outcome. The first two differ by roughly a factor of fifteen in cost, and the cheapest options lose nothing, because the freshness of the output can never exceed the freshness of the input.
This block runs one day in which the warehouse recounts at 02:00. One copy of the count follows the warehouse every minute, and the other is imported once at 03:00:
// The warehouse recounts stock once a night at 02:00. Each count records when it was taken.
type Count = { onHand: number; countedAt: string };
const hhmm = (m: number) => `${String(Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
const yesterday: Count = { onHand: 40, countedAt: "yesterday 02:00" };
let warehouse = yesterday;
// Two ways for the store app to hold a copy.
let synced = yesterday; // real-time sync: copies every minute
let imported = yesterday; // nightly import: copies once, at 03:00
let syncCopies = 0;
let importRuns = 0;
const differ: string[] = [];
for (let minute = 0; minute < 24 * 60; minute++) {
if (minute === 2 * 60) warehouse = { onHand: 37, countedAt: "today 02:00" };
synced = warehouse;
syncCopies++;
if (minute === 3 * 60) {
imported = warehouse;
importRuns++;
}
if (synced !== imported) differ.push(hhmm(minute));
if (minute === 7 * 60) {
console.log(`07:00 sync: ${synced.onHand} units, counted ${synced.countedAt}`);
console.log(`07:00 import: ${imported.onHand} units, counted ${imported.countedAt}`);
}
}
console.log(`minutes the two copies differ: ${differ.length} (${differ[0]} to ${differ[differ.length - 1]})`);
console.log(`copies made: sync ${syncCopies}, import ${importRuns}`);Output
At 07:00 both copies show the same count from the same stocktake. The real-time copy is fresher for one hour, from 02:00 to 02:59, while every store is closed, and it makes 1,440 copies a day to get there.
This is also where "build, buy or skip" belongs. Sometimes the answer is a change in process with no code at all. Sometimes it is a feature of a product you already pay for; many warehouse systems can email a scheduled report. Sometimes it is a script. The nightly import is small enough to show in full:
// Runs at 03:00 from a scheduler. Reads the file the warehouse system
// writes after its 02:00 stocktake and loads it into the store app's table.
import { readFileSync } from "node:fs";
import { Database } from "bun:sqlite";
const db = new Database("store-app.db");
const lines = readFileSync("/imports/stock-latest.csv", "utf8").trim().split("\n");
const upsert = db.prepare(
"INSERT INTO stock (sku, store_id, on_hand, counted_at) VALUES (?, ?, ?, ?) " +
"ON CONFLICT (sku, store_id) DO UPDATE SET on_hand = excluded.on_hand, counted_at = excluded.counted_at",
);
db.transaction(() => {
for (const line of lines.slice(1)) {
const [sku, storeId, onHand, countedAt] = line.split(",");
upsert.run(sku, storeId, Number(onHand), countedAt);
}
})();A production version also alerts when the file is missing and handles quoted CSV fields, and it is still a day of work.
An outcome is ready to build against when a stranger could check it without asking you. Five questions get it there:
- What would you see if it were done? Every store's app showing the 02:00 count, with its time, before 07:00.
- How would a stranger check it without asking you? Open the app at any store at 06:55 and read the time on the count.
- What number, by when? Fewer than two late reorders a week, one month after launch.
- What would make you reject it even if it hit the number? Counts with no time on them, so a manager cannot tell a failed import from a fresh one.
- What is the cheapest check that would catch a failure? A scheduled request at 06:55 that alerts if the newest count predates today's 02:00.
You will not answer the fourth completely up front. Some reasons to reject a result appear only once you see one, and each becomes a new line in the outcome.
Constraints decide which solutions are allowed
Before comparing options you need the fixed facts that rule some of them out. These are constraints, and they come from outside the code. Typical ones are a budget, a deadline, a regulation, an existing system you cannot change, and the skills of the people who will maintain the result.
In the warehouse case, suppose the warehouse vendor offers only a nightly file drop and no API. That one constraint kills the real-time design outright. Suppose the only person who will maintain this is an analyst who knows SQL and a little scripting. That favors a small script over a pipeline with four moving parts. Write constraints down in the same document as the problem, because an agent cannot see the vendor contract or the org chart unless you put them there.
Non-goals are the cheapest fence you can build
A non-goal is a sentence saying what this work will deliberately not do. It costs one line to write, and it gives an agent a stated reason to leave things out.
Growth happens because of how agents fill gaps. Asked for "a small internal tool to track stock", an agent draws on the thousands of tools it has seen, and most of those had user accounts, an admin panel, roles, settings and sometimes a plugin system. Nothing in the brief said this one should not, so the agent adds them. Each addition is reasonable in isolation. Together they turn a one-day tool into a two-week product with a login flow to secure.
For the warehouse case, two non-goals do most of the work:
- Store managers will not edit stock counts in the app. The warehouse system stays the only place counts change.
- The app will not show intraday changes. It shows the 02:00 count and says so on screen.
The first one removes the entire conflict-resolution design, because conflicts need two writers. The second one removes any temptation to poll or stream.
Non-goals are decisions, so they can be revisited. Writing them down turns a silent assumption into something a person can argue with, and when one changes, the date and the reason go into the same document.
Spotting a framing mistake in an agent's spec
Framing mistakes look like good engineering. The spec is detailed, the pieces fit, and the size is wrong. Three patterns come up often, and each has a question that exposes it.

The first is a flexible feature built for a fixed need. An agent is asked to "give managers visibility into weekly sales" and produces a configurable dashboard with a widget builder, saved layouts and date-range filters. Every manager turns out to want the same single number, weekly sales by region, and wants it in their inbox on Monday morning. The flexibility is work nobody will use, and each manager now has to build and open a dashboard to get what a scheduled email would have delivered.
The question that exposes it is: what does the person do with the output next, and when do they need it? If the answer is the same every time, the need is for a delivery, and a builder is a tool for a need that varies.

The second is scope with no boundary. You see an admin panel, a plugin system or a login flow in a tool for four people. The question is: which part of this spec did the requester never ask for, and which sentence in the brief ruled it out? If no sentence could have ruled it out, the brief had no non-goals.
The third is a feature described instead of a problem. You see a real-time sync engine, a streaming pipeline or a cache-invalidation scheme. The question is: how fresh is the source data, and how fresh does the answer need to be for the decision someone makes with it? When the answer to both is "once a day", the design is too big by an order of magnitude.
When a request arrives vague, answer these before any building starts. Who, by role, will use this, and at what moment? What do they do today instead? What decision or task does the output feed, and what happens next? What must this deliberately leave out, and what limits of budget, deadline, rules, existing systems and maintainers surround it? Then put the outcome through the five questions above. The answers you cannot get are the risks to write down.
The problem statement
All of this compresses into one paragraph that opens the written ideal state from Articulating the Ideal State, before any mention of a solution. It names the user, the purpose, the problem, the outcome and at least two non-goals. For the warehouse case:
Store managers at our 12 stores need to decide what to reorder between opening at 07:00 and the warehouse's 08:00 cutoff, so that the shelves hold what customers come in for. Today the stock report arrives by email at 09:00, so about 15 reorders a week go out a day late. Success is every manager seeing the 02:00 stocktake counts before 07:00, and late reorders falling to near zero. Stock counts are read-only in the store app; the warehouse system remains the only place they change. The app shows the nightly count only and makes no attempt to show intraday changes.
An agent given that paragraph is far more likely to propose something close to the nightly import, and if it proposes something bigger you have a sentence to point at. A brief is well framed when a reader can reject a proposed solution by quoting it.