Building Software
Sections

Contents

Section 1 of 9

Ideal State

Knowing and Writing Down What You Want

5 subsections, the core path through it Core 1–2.

Why it matters when agents do the typing

Deciding what to build and what counts as done belongs to the people who need the result and will answer for it. An agent never sees the idea in your head, only what you captured, so every fact you left out becomes its guess. Even an executor that questions the target cannot know what you need better than you do, and no amount of code review fixes a wrong target.

The course: 5 lessons, about 47 minutes of reading, in the order below.

  1. 1.1

    Articulating the Ideal State

    Core 1 · Depth: do

    Getting what is in your head into one written document an agent can build from and a stranger can check: ideal-state prose first, then constraints, dated decisions and criteria.

    A mistake it teaches you to catch: A team switches to a larger model after an agent builds the wrong thing, when the prompt never stated the fact the build got wrong.

    Lesson: Getting What You Want Out of Your Head 8 min

  2. 1.2

    Framing the Problem

    Depth: do

    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.

    A mistake it teaches you to catch: A CSV export button with column pickers built for a request whose real need was the same monthly report sent to an accountant.

    Lesson: The Problem Behind the Request 10 min

  3. 1.3

    Requirements and Acceptance Criteria

    Core 2 · Depth: do

    Turning intent into specific, checkable statements of what the software must do and how well, so done has a definition before work starts.

    A mistake it teaches you to catch: An export feature marked done that silently omits archived records, because no criterion said whether to include them.

    Lesson: Writing Down What Done Means 10 min

  4. 1.4

    Domain Modeling and Invariants

    Depth: do

    Naming the things in the problem, their lifecycles and the rules that must always hold, so code and tests can enforce them.

    A mistake it teaches you to catch: A lifecycle modeled as scattered booleans (isPaid, isShipped, isCancelled) that allows impossible combinations such as shipped but never paid.

    Lesson: Rules That Must Always Hold 9 min

  5. 1.5

    Decisions: Recording Why, Inside the Living Artifact

    Depth: do

    Recording each decision as a dated entry in the project's one living ideal-state document, with the options, their costs and the reason, so later readers, human or agent, can tell a deliberate choice from an accident.

    A mistake it teaches you to catch: A public API field named and shipped during a small bug fix, making the name permanent for every client.

    Lesson: Writing Down Why 10 min

Section test: Ideal State

12 questions across the 5 lessons above. Take it after the course; each answer explains itself.

  1. 1A clinic's appointment-reminder tool was rebuilt from its ideal-state document. A week later the front desk says reminders must never go out on a public holiday, which nobody had mentioned. The agent's pull request adds the lines below. What else has to happen so the next rebuild keeps the rule?
    Diff
      export function shouldSendReminder(appointment: Appointment, today: CalendarDate): boolean {
    +   // Front desk asked: no reminders on public holidays.
    +   if (isPublicHoliday(today)) return false;
        return daysBetween(today, appointment.date) === 1;
      }
    Show the answer

    Answer C. The next build starts from the document, and a rebuild from it would contain neither this comment nor the reason behind it. A dated decision says what changed and why, and a criterion such as no reminder is sent on a public holiday, checked by seeding one, fails any version that sends one. A test is a check without its reason, and it lives beside code the next rebuild may replace; the criterion in the document is what the test should come from. A line in the next prompt lasts for one task.

  2. 2Before building, you asked an agent to say back what it will make from your request for a volunteer sign-up page at a food bank. Today volunteers sign up for Saturday shifts by text message, and the coordinator wants a printed list on Friday evening. What is the cheapest next step?
    Output
    I'll build a volunteer scheduling app. Volunteers create an account, pick
    shifts from a calendar and get email reminders. Coordinators get a
    dashboard with attendance charts and can message volunteers in the app.
    Show the answer

    Answer D. The restatement shows the agent filled the gaps with a typical scheduling app: accounts, email, a dashboard. Sign-up by text and a printed Friday list appear nowhere in it, because they were never written down. Putting those facts in the document now and asking again finds the gap for the price of one message instead of one build. 'Keep it simple' gives the agent no fact to work from, and a larger model would make the same typical guess, since nothing in the request points away from it.

  3. 3An agent turned this problem statement into acceptance criteria. Each criterion is concrete enough for a reviewer to test. What is the main thing wrong with them?
    Output
    Problem: Regional managers set Monday's staffing at 08:30 from last week's sales
    by region. Today the figures arrive on Tuesday afternoon. Success: every manager
    has last week's sales by region by 08:00 on Monday.
    
    Acceptance criteria:
    1. The sales dashboard loads in under 2 s at the 95th percentile with 20 widgets.
    2. A manager can save a custom widget layout.
    3. The date filter accepts any range up to 5 years.
    Show the answer

    Answer B. The criteria are checkable, but they check a dashboard, and the outcome is one fixed set of numbers in each manager's hands before 08:00 on Monday. A dashboard that loads in 1 s, with saved layouts and a 5-year filter, still fails the managers if the data lands on Tuesday. A criterion such as by 08:00 Monday, each manager has received last week's sales by region fails when the outcome fails. Switching criterion 1 to the median would only hide its slowest loads, and it would still be aimed at the wrong target.

  4. 4Operations asks to 'let customers track their deliveries'. An agent builds a tracking page behind the app's login for account owners. The people who wait for deliveries turn out to be site foremen, stored as delivery contacts in the dispatch system, and almost none of them has a login. What went wrong?
    Show the answer

    Answer C. The request used a word, and the agent mapped it to the people who already log in. In dispatch, the person who needs the information is a delivery contact, a separate concept from an account owner, and they need it where they already are, perhaps by text message. Asking who has the problem and what they do today would have shown this before the build. Handing out logins later adds an account per foreman and still puts the page somewhere they do not look.

  5. 5The criterion: two submissions with the same idempotency key never produce two orders or two charges, including two that arrive at the same moment and rows from the partner bulk import. The bulk import inserts rows directly and never calls this function. Which fix meets the criterion?
    TypeScript
    // Called by POST /orders.
    async function createOrder(key: string, cart: Cart) {
      const existing = await db.query("SELECT id FROM orders WHERE idempotency_key = $1", [key]);
      if (existing.length) return existing[0].id;
      const id = await db.insertOrder(key, cart);
      await payments.charge(id, cart.totalCents);
      return id;
    }
    Show the answer

    Answer A. Two requests can both run the SELECT before either inserts, so the check lets both through, and the bulk import skips the check entirely. A unique index makes the database refuse the second row on every write path, at the same moment or not, and the insert then returns the order that already exists before any second charge. Disabling the button stops one double click in one browser and does nothing for retries, a second tab or the import. A nightly cleanup admits the double charge happened. Finishing a charge that a crash interrupted between insert and charge is a separate requirement; this criterion is about duplicates.

  6. 6Customers can now download every message they have sent or received, and these criteria all pass. The agent built the query by copying one from the support tool, which searches every account. Which added criterion and check would have caught it?
    Output
    1. The download includes every message the customer sent or received.
       Check: a fixture with one customer, 4 sent and 3 received messages;
       expect 7 rows.
    2. Archived messages are included and marked "archived".
       Check: the same fixture with 2 of the messages archived.
    3. A download of 10,000 messages finishes in under 30 s.
       Check: a timed run against a seeded copy.
    Show the answer

    Answer D. Every criterion says what the download must include, and a query with no account filter includes all of that plus everyone else's messages, so the one-customer fixture passes all three. An anti-criterion states what must never happen, and its check has to set up the forbidden case: a second customer with messages of their own, and an assertion that none of them appear. A larger fixture with still one customer cannot fail either. A judge reading the file cannot tell whose rows are whose, and code can check it exactly.

  7. 7This compiles under strict, and the scenario Given a paid order, When it ships, Then its status is shipped passes. The warehouse feed omits paymentRef for orders it ships before the app has recorded a payment. What is wrong?
    TypeScript
    type Order =
      | { status: "awaiting_payment"; id: string; totalCents: number }
      | { status: "paid"; id: string; totalCents: number; paymentId: string }
      | { status: "shipped"; id: string; totalCents: number; paymentId: string; trackingNumber: string };
    
    type FeedRow = { orderId: string; totalCents: number; paymentRef?: string; tracking: string };
    
    // Added by the agent: orders the warehouse ships before the app hears about them.
    function fromWarehouseFeed(row: FeedRow): Order {
      return {
        status: "shipped",
        id: row.orderId,
        totalCents: row.totalCents,
        paymentId: row.paymentRef ?? "unknown",
        trackingNumber: row.tracking,
      };
    }
    Show the answer

    Answer B. The type only says a shipped order carries a string, and unknown is a string, so the check passes while the rule that shipped means paid is broken. The scenario covers the path through ship and says nothing about the feed, which is a second write path the criteria forgot. A foreign key from payment_id to the payments table, or sending the feed through ship, would refuse the row. The first option trusts the type for more than it promises.

  8. 8The invariant: the total refunded on a payment never exceeds the payment. Which case breaks it while every call passes this check?
    TypeScript
    async function refund(paymentId: string, amountCents: number) {
      const payment = await db.payments.get(paymentId);
      if (amountCents > payment.amountCents) throw new Error("refund exceeds payment");
      await db.refunds.insert({ paymentId, amountCents });
    }
    Show the answer

    Answer A. The check compares one refund with the payment, and the rule is about the sum of all refunds on it. Two 60% refunds each pass and together return 120%. A duplicated request, or two refunds at the same moment, gets through the same way. The check has to include the refunds already recorded, and it has to be safe against concurrent calls, with a lock or a single statement. The 1-cent case is the one this code was written for, and it throws.

  9. 9The criterion says customers whose orders are fulfilled do not get the 'Where is my order?' email. An agent wrote the query at the end. What does it return?
    SQL
    CREATE TABLE orders (
      id     TEXT PRIMARY KEY,
      email  TEXT NOT NULL,
      status TEXT NOT NULL CHECK (status IN ('awaiting_payment','paid','shipped','delivered'))
    );
    INSERT INTO orders VALUES
      ('o-1', 'a@example.com', 'paid'),
      ('o-2', 'b@example.com', 'shipped'),
      ('o-3', 'c@example.com', 'delivered');
    
    -- Customers who still get the "Where is my order?" email.
    SELECT email FROM orders WHERE status <> 'fulfilled';
    Show the answer

    Answer C. The criterion uses the business's word, and the schema has no state by that name, so status <> 'fulfilled' is true for every row and every customer gets the email. A CHECK constraint limits what can be written; a SELECT can compare with any string without an error. The fix starts before the code: ask operations whether fulfilled means shipped or delivered, then use that one word in the criterion, the query and the schema.

  10. 10When the team moved transactional email to a hosted provider, an agent edited the project's ideal-state document like this. What is wrong with the edit?
    Diff
      ## Decisions
    - 2026-02-10: Send transactional email through our own SMTP server.
    -   Why: under 500 emails a day, and no vendor contract to manage.
    + 2026-02-10: Send transactional email through a hosted provider.
    +   Why: volume passed 20,000 a day and our sending IP is on two blocklists.
    Show the answer

    Answer A. The ideal state, constraints and criteria are edited in place so they say what is true now; the decisions log is the one part that only grows. This edit erased the SMTP decision and its reason, and it dates the provider choice to a day when nobody made it. An agent that later proposes running a mail server again finds no sign the team tried one and left it. A new entry dated today, naming the one it supersedes, keeps both. A reason in a commit message sits where an agent working from the document does not look.

  11. 11These lines come from one project's ideal-state document: the first from its criteria, the second from a decision entry in its log. What should happen before anyone builds?
    Markdown
    Criterion 4: Each merchant receives each order webhook exactly once.
    
    Decision 2026-03-04 (outbox table): If a worker crashes after sending a
    webhook and before marking its row sent, another worker sends that webhook again.
    Show the answer

    Answer D. The decision entry says the design sends some webhooks twice, so criterion 4 is false for it, and a test that kills a worker mid-batch would fail rather than pass. One side has to move: either a new entry changes the ideal state to at-least-once delivery, and criterion 4 with it, with a stable event ID that merchants use to drop duplicates, or the team picks a different design. A queue has its own gap, where the order commits and the publish fails, so swapping it in does not make the conflict go away.

  12. 12A decision entry in a project's ideal-state document chooses an outbox table for webhooks. Which Revisit when line could a reader six months from now check without asking anyone?
    Show the answer

    Answer B. A revisit condition works like an acceptance criterion: it needs something a person can observe and a threshold that gives a yes or a no. The 95th-percentile line names a metric, a number and a duration, so anyone with the delivery dashboard can tell whether it has fired. 'Too slow' and 'change significantly' have no threshold, so every reader judges them differently. 'Time to move' describes the team's schedule and says nothing about whether the original reasoning still holds.