Writing Down Why
An agent is asked to make webhook delivery more reliable. It reads the code and finds a worker that polls a database table every two seconds for unsent webhooks. Then it finds docs/design/webhooks.md, written before the work started, which says order events go to a managed message queue. The agent concludes that the code drifted from the design and proposes to bring it back in line: replace the table with the queue, about 400 lines, with the design document cited as the reason.
Each step of that reasoning holds up, and the conclusion is wrong. Three weeks into the build, the team abandoned the queue on purpose. They had one engineer on call, they already ran the database, and a queue would have been a second stateful system to secure, monitor, back up and wake up for at 03:00. That reasoning lived in a meeting and a chat thread. Nobody updated the design document, because it had done its job once the work started.
The code shows what the team built and says nothing about why, or about the paths they tried and left. For the next reader, human or agent, to tell a deliberate choice from an accident, the reason has to sit where that reader looks, and stay current.
One document, kept current
An agent works from text it can read. A reason can live in three places, and each behaves differently when the agent arrives:
- In a person's head or a chat thread. The agent never sees it.
- In a separate design document written before the work. The agent sees it, but it records the plan on the day it was written. Once building teaches the team something, the document is wrong, and it is wrong in a confident, well-formatted way.
- In the document the work is built against, updated as part of the work. The agent sees it, and it says what is true now.
The third is the ideal-state document from the first lesson of this section: one file per project holding the ideal state in prose, the constraints, the criteria that check it, and a log of decisions. Daniel Miessler, who calls his version an Ideal State Artifact (ISA), describes the log this way: when building teaches you something or changes your mind, "you write it back into the ISA with the date and the reason, so the iteration happens in the articulation instead of getting lost in the code."

The design file in the opening failed because it was written once and then left alone while the plan changed under it. A log written during the work records each change on the day it happens, in the file the agent already reads.
What the criteria cannot say
The criteria in the document say what must be true. For the webhooks: every committed order produces exactly one webhook event, a merchant whose server was down hears about every order once it is back, and checkout never waits on a merchant. The build is checked against them.
Now hold the agent's queue proposal up to those criteria. Built carefully, with the failed-publish case handled, a queue passes every one. The evals go green. The team's reason for the table was the cost of running a second stateful system with one engineer on call, and that cost belongs to the design, so no criterion measures it.
You could add a constraint, "no new stateful systems", and the agent would obey it. It would still have no way to tell when the constraint should be lifted, because the reason and the conditions for reopening it are missing.
Decision entries cover what the criteria leave open. When several designs would all pass, the entry records which one the team chose, what each option cost, and the facts the choice rested on. When building changes what the team wants, the entry records that change, and the ideal state and criteria are edited to match.
A decisions log, worked
Here is part of the webhook project's document a few weeks into the build:
# Order webhooks
## Ideal State
When a customer places an order, the merchant's server hears about it within
seconds. Merchants' servers are sometimes down for minutes; a merchant whose
server was down hears about every order once it is back. Checkout never waits
on a merchant. A merchant may receive a webhook twice and deduplicates on
`event_id`. One on-call engineer can run this without being woken for it.
## Constraints
- Runs on the PostgreSQL database we already operate (see 2025-10-02).
## Criteria
- ISC-1: A committed order produces exactly one webhook event; a rolled-back
order produces none. Check: test that aborts the order transaction.
- ISC-2: A merchant down for up to 3 hours receives every pending webhook
within 10 minutes of coming back. Check: fake merchant, simulated clock.
- ISC-3: Checkout p95 does not change when a merchant takes 30 s to answer.
Check: load test against a slow fake merchant.
- ISC-4: Every webhook carries an `event_id` that is the same on a resend.
Check: test that kills the worker after a send, before it records the send.
## Decisions
- 2025-09-08: Publish order events to a managed message queue. Why: the usual
tool, and other services may want order events later.
- 2025-10-02: Supersedes 2025-09-08. Write each webhook to an `outbox` table in
the order's transaction; a worker polls it every 2 s and sends.
Options: (A) send inside the order request: fails ISC-3, and a failed request
loses the webhook. (B) outbox table: no new system; delivery starts within
about 2 s when the worker is idle. (C) queue: far higher volume and fan-out,
but a second stateful system to secure, monitor and back up, and a new
failure where the order commits and the publish fails.
Why B: one engineer on call; PostgreSQL already runs; peak is 20 webhooks/s,
measured; merchants accept a few seconds of delay but not a lost webhook.
Gives up: fan-out to other consumers.
Revisit when: peak passes 500/s, or a second service needs order events.
- 2025-10-20: A worker crash after the send and before COMMIT sends the
webhook again. Changed the ideal state: a merchant may receive a webhook
twice and deduplicates on `event_id`. Added ISC-4. Why: three large
merchants confirmed they can deduplicate, and exactly-once delivery would
need their cooperation anyway.
- 2025-11-12: Capped retry backoff at 5 minutes, down from 1 hour. Why: ISC-2
failed; with a 1-hour cap a webhook could wait almost an hour after the
merchant recovered. Costs: about 290 tries per pending webhook in a day-long
outage, up from about 30.The 2025-10-02 entry has the parts every decision entry needs. It names the entry it supersedes, so the queue plan stays readable next to its replacement. It lists the real options, each with its cost beside its benefit. It gives the facts the choice rests on, with numbers, and says the volume was measured. It names what the team gave up. Its last line says when to reopen the question, which turns a future argument into a check anyone can run.

outbox row in one transaction, so a webhook exists if and only if the order does.Option B works because the order and its outbox row are written in one transaction: both rows or neither, so a webhook exists if and only if its order does. Option A slows checkout whenever a merchant's server is slow.
The next two entries were written because building taught the team something. Here is the worker that option B needs:
BEGIN;
SELECT id, event_id, merchant_url, payload
FROM outbox
WHERE sent_at IS NULL AND next_attempt_at <= now()
ORDER BY next_attempt_at, id
LIMIT 50
FOR UPDATE SKIP LOCKED;
-- send each webhook with a 5-second timeout, then for each one that succeeded:
UPDATE outbox SET sent_at = now() WHERE id = $1;
-- and for each one that failed: wait 10 s, 20 s, 40 s ... up to the cap
UPDATE outbox
SET attempts = attempts + 1,
next_attempt_at = now() + LEAST(interval '5 minutes', interval '10 seconds' * power(2, LEAST(attempts, 5)))
WHERE id = $1;
COMMIT;FOR UPDATE locks the selected rows until the transaction ends, and SKIP LOCKED tells a second worker running the same query to pass over rows the first one holds instead of waiting. If a worker crashes mid-batch, its transaction rolls back, the locks release, and another worker picks the rows up.

COMMIT, so the row rolls back unsent and worker 2 sends it again.That recovery has a price nobody saw on 2025-10-02. A worker that sent a webhook and then crashed before COMMIT leaves the row unsent in the database, even though the merchant already has it, so the next worker sends it again. The team chose to change what they promised. The 2025-10-20 entry rewrites the ideal state so a merchant may receive a webhook twice and deduplicates on event_id, and adds ISC-4 to check that the id survives a resend. An entry like this changes the target itself, so the prose and the criteria are edited in the same change, and the document never promises one thing while checking another.
The 2025-11-12 entry came from a failing criterion. The worker first capped its backoff at an hour, and ISC-2 says a merchant down for up to three hours gets every pending webhook within ten minutes of coming back. This block checks both caps against ISC-2:
// One webhook, first tried at second 0, to a merchant whose server is down for `downFor` seconds.
// After its nth failure the worker waits min(cap, 10 × 2^(n - 1)) seconds before trying again.
function deliver(downFor: number, cap: number) {
let at = 0;
let tries = 0;
for (;;) {
tries++;
if (at >= downFor) return { tries, lateBy: at - downFor };
at += Math.min(cap, 10 * 2 ** (tries - 1));
}
}
for (const cap of [3600, 300]) {
// ISC-2: any outage up to 3 hours, checked every 10 seconds of outage length.
let worst = 0;
for (let down = 10; down <= 3 * 3600; down += 10) worst = Math.max(worst, deliver(down, cap).lateBy);
const day = deliver(24 * 3600, cap);
const isc2 = worst <= 10 * 60 ? "PASS" : "FAIL";
console.log(`cap ${cap / 60} min: ${isc2} ISC-2, worst wait after recovery ${worst} s, tries in a 24 h outage ${day.tries}`);
}Output
With the 1-hour cap, a merchant that recovers just after a failed try waits almost an hour for the next one, so ISC-2 fails. With a 5-minute cap the worst wait is under 5 minutes. The fix costs something too: in a day-long outage each pending webhook is tried 293 times instead of 33. The entry records both, so whoever wants to raise the cap later knows which criterion it protects and what it costs.
Now give the agent from the opening this document instead of the stale design file. It finds the queue plan, sees that 2025-10-02 supersedes it, and reads the revisit line: is peak volume near 500 a second, and does another service need order events? If neither is true, the queue brings back the cost the team chose to avoid and solves nothing they have. If one is true, the agent can say so, cite the entry, and propose a new one. Either way the decision is made against the original reasoning.
Change by appending
The ideal state, the constraints and the criteria are edited in place, so they always say what is true now. The decisions log is the one section that only grows. When a decision changes, you add a dated entry that names the one it replaces, and you leave the old entry where it is.
Rewriting the old entry looks tidier and destroys the record. The 2025-09-08 entry still says "use a queue", and that line earns its place: it shows the next reader that the team already considered the agent's idea, and the entry below it says why they moved off it.
Michael Nygard's architecture decision records, short numbered files with context, decision and consequences, carry the same parts. Here they live in the document the build is checked against, next to the criteria they explain.
Which decisions need an entry
What it costs to reverse a decision should decide how carefully it is made. Jeff Bezos's shareholder letters describe the split as one-way and two-way doors. A two-way door is cheap to walk back through: a function name, an internal library, a log format. Make these quickly and fix them if they turn out wrong. A one-way door is expensive or impossible to reverse. Slow down, get a second opinion, and write the entry before it ships.
The practical test is to count who depends on the choice and whether you control them. An internal function name has callers only in your repository, so you can rename it in one commit. A column in your own database is harder, because data already exists in that shape and you need a migration, but you still control every step. A field in a public API is at the far end. Once a client has written code that reads customer_name, you cannot rename it without breaking that client, and you do not control when they upgrade. The name is effectively permanent.

customer_name, it is effectively permanent.This is how a small change becomes a large decision without anyone noticing. An agent fixing a bug in an order endpoint adds a field to the JSON response because it needed it for the fix, and names it cust_nm to match a database column. The change is ten lines, and it ships as a bug fix. A merchant's integration starts reading the field, and the team now supports that name for years.
The question that finds these is whether a change adds or alters anything a party outside your control will read or write. It can run without a person: a test that compares each public response's fields against the fields the document lists for the API fails the build when a new one appears, which sends the change to someone who can write the entry. Data formats, storage engines, public identifiers and anything customers integrate against are usually one-way. Most internal code structure is two-way, and the code and its commit message are record enough.
Options with their costs
The weakest decision entries list options with an advantage for each and then stop. "Option A is simple. Option B is scalable. Option C is flexible." Nothing is chosen, and the reader learns nothing about what any option costs. Agents produce this shape often when a prompt asks them to compare options and never asks them to choose.
The fix is to require the cost of every option alongside its benefit, in the same units where you can: how many new systems or concepts, how many weeks, a monthly bill, what fails and how badly. Then the entry has to name one option and say what it gives up. An entry that ends with "any of these would work" has no decision in it, and the next reader has to redo the whole analysis.
Estimates belong in the entry
Estimates go in the entry too, written as ranges. "Two to five weeks" tells a reader more than "three weeks", because the width shows how much is still unknown. When the range is wide, find the unknown that makes it wide and settle that first. When the duplicate problem surfaced, the estimate for finishing went from two weeks to two to five, and most of the width came from one question: could the large merchants deduplicate? A day asking three of them narrowed the range more than a week of building the easy parts would have, and their answer became the reason in the 2025-10-20 entry.
Reading a decisions log
When you read an entry, whether a colleague or an agent wrote it, look first for the sentence that states the decision. If there is none, the entry compares options without choosing, and the choice is still open.
Then find the assumption the decision rests on and ask how sure anyone is of it. In the 2025-10-02 entry it is the volume: 20 webhooks a second, and the choice holds while volume stays well below 500. A measured 20 is worth more than a guessed one. Is a sales deal about to add a merchant ten times larger than any current one? An assumption that a known event is about to break deserves a new entry now, before the revisit line fires.
Then check whether the entry changed what the project wants. If it did, the ideal state and the criteria should show the same change. An entry saying merchants may get duplicates, next to a criterion that still demands exactly one delivery, gives the agent two instructions and no way to pick.
An entry is complete when an agent reading it six months later can tell, without asking anyone, whether its change undoes a deliberate choice.