Building Software
Sections

Contents Section 1, Ideal State

Framing the Problem

Working out who has the problem, what outcome would solve it, and what is deliberately out of scope, before any solution is on the table.

Section 1 of 9, subsection 2 of 5. Depth: do. A 10-minute read.

Mistakes to catch in review

  1. A CSV export button with column pickers built for a request whose real need was the same monthly report sent to an accountant.

  2. An admin panel, a plugin system or a login flow added to a small tool because the brief never said what was out of bounds.

  3. A real-time sync engine built when users only needed a nightly import, because the brief described a feature instead of the problem.

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 large box labelled in their head holds two boxes: Pain, the real X, with an arrow to Imagined fix, their Y. An arrow leaves the box from the imagined fix down to Request, which describes the fix, and the request flows to Agent, which builds Y at full size. The pain never leaves the box. A dashed arrow runs from the agent back up to the pain, labelled go back, find X. A note under the agent says the pain is left behind.
The request you receive describes a fix someone imagined, and the agent builds that fix. The pain that started it never reaches the brief unless someone goes back for it.

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.

A timeline from left to right. At 02:00 the warehouse recounts stock. An arrow labelled no newer count leads to a highlighted decision window holding 07:00, stores open, and 08:00, reorder cutoff. An arrow then leads to 09:00, stock report emailed, and down to late reorders, about 15 a week. A note under the window says data needed before 07:00.
The only new count appears at 02:00 and the reorder decision happens between 07:00 and 08:00, but the report arrives at 09:00. The numbers are fresh enough; they arrive after the moment they are needed.

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:

TypeScriptRuns in your browser
// 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}`);

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:

TypeScript
// 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:

  1. What would you see if it were done? Every store's app showing the 02:00 count, with its time, before 07:00.
  2. 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.
  3. What number, by when? Fewer than two late reorders a week, one month after launch.
  4. 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.
  5. 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.

An arrow from Same number, weekly sales by region, goes up to Dashboard, what the agent built, which reaches Manager by a dashed arrow marked Build, open. A second arrow goes down to Monday email, what they needed, which reaches Manager directly. A note says the need is a delivery.
Every manager wants the same number at the same time. A dashboard makes each of them build and open it; a scheduled email simply delivers 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.

A flow from left to right. Small-tool brief, with no non-goals, leads to Agent fills gaps, from tools it has seen. That leads to a group labelled reasonable in isolation holding user accounts, admin panel, roles, settings and plugin system. The group leads to Two-week product, which must secure its login. Notes say no sentence ruled it out, and one-day tool, two-week product.
Each addition is reasonable on its own, and no sentence in the brief rules any of them out. Together they turn a one-day tool into a two-week product.

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.

Check your understanding

6 questions on this lesson. Pick an answer to see whether it holds and why.

  1. 1A product manager sends an agent one line: "Add notifications to the app." Which question should be answered before any of the others?
    Show the answer

    Answer B. Channel, volume and settings are design choices, and each one only has a right answer once you know who needs to learn what, and by when. Asking about push versus email first lets the request's own solution pick the delivery method before anyone has named the person or the moment.

  2. 2An agent wrote this to keep the store's prices in sync with a supplier. The supplier publishes a new price list with changed prices once a week, on Monday at 06:00. The stored prices start out matching the supplier's list, and each poll finishes in under a second. Of the polls in a week, how many can change what customers see?
    TypeScript
    // Keeps the pricing page in sync with the supplier's price list.
    setInterval(async () => {
      const prices = await supplier.getPriceList();
      await db.replacePrices(prices);
    }, 10_000);
    Show the answer

    Answer C. The loop runs 60,480 times a week and the source changes once, so only the first poll after the new list appears brings anything new. The other 60,479 write the same list again. A copy can never be fresher than what it copies, so one successful import after publication retrieves the same list. Whether its delay is acceptable depends on how fresh the prices need to be.

  3. 3An agent wrote this problem statement for a clinic. What is its main defect?
    Output
    Problem: The clinic needs an online booking system. It should let
    patients pick a time slot, send an SMS reminder the day before, and
    let staff manage the calendar. Success: the booking system is live
    by March.
    Show the answer

    Answer A. Nothing in it says who is struggling today or how you would know the system helped, such as fewer no-shows or fewer calls to the front desk. Leaving out the database is fine at this stage, because technology is a design choice. Without the problem, an agent builds every listed feature at full size with nothing to compare them against.

  4. 4An agent produced this spec for a page where four warehouse supervisors see today's deliveries. The logistics system exports the schedule each night. Which non-goal removes the conflict-resolution work entirely?
    Output
    1. Supervisors can edit delivery times on the page.
    2. When the next nightly export disagrees with an edit, show both
       values and let a supervisor pick one.
    3. Push live updates to every open page.
    4. User accounts with supervisor and admin roles.
    Show the answer

    Answer D. Conflicts need two places that can change the same value. Once the logistics system is the only writer, item 2 has nothing to resolve and item 1 goes with it. Dropping live updates is tempting because it sounds related, but two writers would still disagree on a page that only reloads.

  5. 5A team lead asks for an app so engineers can request time off. Today engineers post in a team chat channel and the lead copies each request into a shared calendar. Which question tells you most about whether anyone will switch to the app?
    Show the answer

    Answer B. The chat-and-calendar routine is the tool the app replaces, and people switch only for what it fails at, such as requests lost in the scroll or a lead who forgets to copy one. That failure sets the minimum bar. Knowing which chat tool they use helps with integration later, and it says nothing about why anyone would change.

  6. 6An agent's plan for a head-office sales report opens like this. Given the constraints in the brief, what should happen to the plan?
    Output
    Plan: stream every sale from the 40 stores to head office through the
    point-of-sale vendor's real-time API, with a queue and retries.
    
    Constraints (from the brief):
    - The point-of-sale vendor offers a nightly file export. It has no API.
    - The person who will maintain this is one analyst who knows SQL.
    Show the answer

    Answer A. A constraint rules options out before anyone weighs them. With no API there is nothing to stream from, so a cost comparison is wasted effort, and the analyst constraint already points toward a small import script. A dead-letter queue only makes an impossible design more elaborate.

You understand it when you can

Drill

An agent was asked to 'add export so customers can get their data' and produced a spec for a CSV button with column pickers and date filters. The support tickets behind the request say customers' accountants need the same report every month; find what the spec misses and rewrite the problem statement with two non-goals.

Topics

Users and the Jobs They Need Done
Identifying who has the problem and what they are actually trying to accomplish when they reach for software.
Outcomes Over Features
Stating success as a change in the world, such as fewer failed payments or faster onboarding, so solutions can be compared against it.
Scope and Non-Goals
Writing down what the work will not do, which is the cheapest way to stop an agent from expanding the task.
Build, Buy or Skip
Deciding whether the problem needs new software at all, or an existing product, a script or a change in process.
Constraints
Budget, deadlines, regulations, existing systems and team skills that decide which solutions are acceptable.

Further reading

Start here

  • Shaping in a Nutshell. Ryan Singer, 2022. 18-minute explainer.

    In under twenty minutes, the author of Shape Up explains setting an appetite, narrowing a raw request to the real problem and naming no-gos before any building starts.

Short reads

  • How to Get Startup Ideas. Paul Graham, 2012.

    Shows how to find problems people actually have instead of ones that only sound good, which is the first question to ask before any build.

  • Hammock Driven Development (transcript). Rich Hickey, 2010.

    Argues that most bugs are misunderstandings of the problem, and describes how to think a problem through before anyone writes code.

  • The XY Problem. xyproblem.info.

    One page on the most common framing error: asking for help with your attempted fix instead of the problem you started with.

Watch

Books

  • Continuous Discovery Habits: Discover Products that Create Customer Value and Business Value. Teresa Torres, 2021.

    Shows how to state an outcome, build an opportunity solution tree from customer interviews and compare candidate solutions against that outcome instead of against a feature list.

  • Shape Up: Stop Running in Circles and Ship Work that Matters. Ryan Singer, 2019. Free to read online.

    Its shaping chapters teach how to turn a vague request into a bounded pitch with an appetite, a problem statement, rabbit holes and explicit no-gos.

  • Competing Against Luck: The Story of Innovation and Customer Choice. Clayton M. Christensen, Taddy Hall and 2 others, 2016.

    The book-length treatment of jobs-to-be-done, including how to find which existing product or workaround a new solution has to replace.

Primary sources