The Assumption Register
A running list of what the system takes as true, when it was decided, why, what depends on it and what would make it false — kept beside the unknowns and the decisions, reviewed when a requirement arrives, and retired rather than deleted. The unknowns board is where it lives.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
You have learned to notice assumptions. Where do they go so that the team finds them at the moment a requirement changes — and how is the list kept alive without becoming another document nobody reads?
I have been writing assumptions down — in commit messages, in a design doc, in a comment above the inventory table. When the founder asked about the second warehouse I could not find half of them, and the ones I found did not say what depended on them. I need a place, and a way of keeping it current.
Write an ASSUMPTIONS section in the design document. It is the natural home: the doc describes the design, and the assumptions are part of it. A heading and a bulleted list, done in ten minutes, and now there is a place.
The design doc is written once and read at review. Assumptions are made continuously — every simplification chosen to ship a feature is one — and the section reflects the design as it was the week the doc was written. Six months later it lists three assumptions and the code embodies twenty.
- The design doc is written once and read at review. Assumptions are made continuously — every simplification chosen to ship a feature is one — and the section reflects the design as it was the week the doc was written. Six months later it lists three assumptions and the code embodies twenty.
- A bulleted list has no room for dependents, reasons or dates. "One warehouse" in a list is a word; "one warehouse, chosen at V1 to keep inventory a number, depended on by these six things, false when a second location holds stock" is a tool. The section format invites the word.
- Nobody opens the design doc when a requirement arrives. The moment the register is for — "which of these does the new requirement contradict?" — is a moment people open the issue tracker or the code, not a document from the project's first month.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Give assumptions a fixed shape and a fixed home. The shape: the assumption as a sentence; when and by whom; why (to simplify, because someone said so, never noticed); what depends on it; what would make it false; status (active, under review, retired — with what replaced it). The home: the same board the unknowns and decisions live on, because they are three views of the same thing — what the team knows, what it is finding out, and what it is taking on faith (The Unknowns Board).
- Make the register part of two existing moments rather than a new ritual. When a simplification is chosen to ship — one currency, accounts required, synchronous email — the entry is written then, as part of choosing. When a requirement arrives, the first question asked of it is "which entries does this contradict?", and the answer is written on the requirement. Neither adds a meeting; both add a minute.
- Promote and demote. An assumption that turns out to have an owner moves to requirements (Assumption vs Requirement); one that can be checked cheaply becomes an unknown with an experiment and then a fact; one that a requirement contradicts is retired with the date and its replacement. The register is a queue as much as a record, and entries are expected to leave it.
- Keep it small by keeping it honest: only assumptions a plausible requirement could contradict within the life of the system. "The database will exist" is not an entry; "one region" is, if the founder has mentioned another country (What Can I Ignore for Now?).
The register as the board's assumed column
The unknowns board already has the shape: known, unknown with a question and an experiment, assumed. The register is the assumed column taken seriously — each entry carrying reason, dependents and false-when — and read together with the other two, because an assumption that can be checked cheaply is an unknown with an experiment, and an unknown that gets answered becomes a known. The board below is the store's after the country requirement arrived.
- ✓The provider supports charges in the second country's currency (checked in its documentation this morning).
- ✓Shipping abroad from the one location is possible; the assumption "one warehouse" is not contradicted.
- ~One currency — never chosen; dependents: bare-number prices, totals, provider call, reports; false when a price or customer is in a second currency — CONTRADICTED by this requirement; under review with finance.
- ~One timezone — never chosen; dependents: raw timestamps, daily report, sale start times; false when customers are in a second zone — CONTRADICTED by this requirement.
- ~Two locations, no split shipments, no transfers — chosen when the second warehouse shipped; dependents: allocation rule, sold-out semantics — false when an order cannot be fulfilled from one location; active.
? Taxes abroad.
becomes Does the second country require tax to be shown per line or per order, and does the provider compute it or must we?
experiment Read the provider's tax documentation for that country and place one test-mode charge with a line-level tax to see what it returns.
? Does finance own the currency assumption?
becomes Would a second currency in the order table break the finance report, and would they accept a per-currency total for the first year?
experiment Show finance one order in the second currency in a test environment and ask what their report does with it.
The contradicted entries are the estimate: two assumptions, their dependents, and two unknowns with experiments. Nothing about the warehouse.
The shape of an entry
The entry format, as text, with the refusal rule built in: an entry without dependents is sent back. The fields are ordered so that the two most-read ones — dependents and false-when — are where a reader skimming for "does the new requirement contradict this?" will find them.
1ASSUMPTION one currency2WHEN / WHO V1, never chosen — noticed during the assumptions pass3WHY prices were entered as numbers; nobody asked otherwise4DEPENDS price is a bare number; totals add bare numbers;5 provider call hard-codes the currency; reports sum across orders6FALSE WHEN a price, a customer or a report is in a second currency7STATUS under review — finance may own this (see unknown: finance report)8 9ASSUMPTION one warehouse10STATUS RETIRED — replaced by "two locations", "no split shipments",11 "no transfers"; see those entries12WHY RETIRED second location opened; requirement contradicted this entry13 14(refused) ASSUMPTION products have one price15 DEPENDS ? <- no dependents listed; send backThe refused entry is the format doing its job. "Products have one price" may well belong in the register; it enters when someone has said what depends on it.
The two moments, and what happens at each
The register is kept alive by attaching it to moments that already happen, not by adding a review. The pipeline below is the whole process; its failure column is what the design-doc section does instead at each stage.
- 1Choose a simplification
Write the entry — with dependents — as part of choosing. "We'll send email synchronously for now" gets its entry the same minute.
fails by The entry is deferred to the design review, where the simplification is remembered as a fact rather than a choice.
- 2A requirement arrives
Read the register; write "contradicts: …" on the requirement before estimating; those entries' dependents are the estimate's skeleton.
fails by The estimate is built from the requirement's wording, and the dependents are discovered during the work.
- 3An entry is contradicted
Run When Assumptions Change; on completion, retire the entry with its replacements.
fails by The entry is deleted, or left active and wrong.
- 4An entry can be checked cheaply
Move it to unknowns with an experiment; on the answer, it becomes a known or a requirement.
fails by It stays assumed because recording was easier than asking.
- 5An entry finds an owner
Promote it to requirements; the design's posture toward it changes from isolate to enforce.
fails by It stays an assumption the design is allowed to drop, and the owner finds out when it is dropped.
There is no "review the register" step. Entries move at the moments the work already has; a register that needs its own meeting is a register nobody will read.
How to do it
Most important first.
- Adopt the shape — assumption, when, why, dependents, false-when, status — and refuse entries that lack dependents. The dependents are what make the entry useful later.
- Put the register on the unknowns board, in the assumed column, so that the three lists are read together.
- Write the entry at the moment a simplification is chosen. Not in the design review, not at the retrospective — when the choice is made.
- On every incoming requirement, ask "which entries does this contradict?" and write the answer on the requirement before estimating it.
- Retire, never delete. A retired entry with its replacement is how next year's engineer learns why the inventory model looks the way it does (The Engineering Notebook).
Worked on a concrete problem
The move has to produce something. This is what it produced.
- The store's register after the first pass, in the shape: "One warehouse — V1, engineer, to keep inventory a number — dependents: inventory column, shipping origin, admin editor, reservation invariant, sold-out check, reorder report — false when a second location holds stock — active." "One currency — V1, never chosen, noticed during the assumptions pass — dependents: bare-number prices, totals, provider call, reports — false when a price or a customer is in a second currency — under review: finance may own this." "Customers have accounts — V1, founder, legal identity per order — promoted to requirements."
- A requirement arrives: "sell in a neighbouring country". Read against the register: contradicts "one currency" (under review — now urgent), contradicts "one timezone" (dependents: raw timestamps, the daily report, sale start times), does not contradict "one warehouse" (shipping abroad from one location is fine). The estimate is built from two entries' dependents, and the founder hears which parts of the system the country touches and which it does not.
- After the second warehouse ships, the entry is retired: "One warehouse — retired, replaced by: two locations, no split shipments, no transfers (see entries)". The three replacements are new assumptions with their own dependents, and the first of them — no split shipments — already has a plausible contradicting requirement written next to it.
How you know it worked
What now exists that did not before, and what question you can now ask.
- There is one place, and every entry in it has dependents and a false-when; entries without them were refused.
- New simplifications appear in the register on the day they are chosen, because writing the entry is part of choosing.
- Incoming requirements carry a line saying which entries they contradict, written before the estimate.
- Entries leave: promoted to requirements, resolved into facts, or retired with a replacement — and the register is not growing without bound.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?When a simplification was chosen to ship this feature, was its entry written at the same moment — and does it have dependents?
- ?For this incoming requirement, which register entries does it contradict, and have I written that on the requirement before estimating?
- ?Which entries could be promoted, resolved or retired this week, so that the register stays a queue rather than an archive?
- ?Could next year's engineer explain why the model looks the way it does from the retired entries alone?
What can go wrong
- The register becomes a compliance artefact: every feature must "update the assumptions" and the entries become boilerplate with no dependents. The refusal rule — no dependents, no entry — is what keeps it a tool.
- It is kept somewhere separate from the unknowns and decisions, and so read separately, which means not read at the moment a requirement arrives.
- Retired entries are deleted for tidiness, and the archaeology this lesson exists to prevent is reintroduced one level up: nobody can say why the model is per location.
- The register replaces the conversation. An assumption that could be settled by asking the founder today is recorded instead, because recording is easier than asking.
- A fixed shape with required dependents is more work per entry than a bulleted list, which is why the list is the reflex and the register is the move.
- Reading the register against every requirement is a minute per requirement, forever.
- A register that is kept honest is short, which can look to a stakeholder like the team has not thought of much; the length is a feature and needs saying.
- "This is the design doc's assumptions section." A section is written once; a register is written at the moment each simplification is chosen and read at the moment each requirement arrives. The difference is when, not where.
- "The register should be exhaustive." It should contain what a plausible requirement could contradict. An exhaustive register is unread; a short honest one is opened when it matters.
- "Retired entries are clutter." They are the only record of why the system has the shape it has. The retired "one warehouse" entry is the answer to a question a new engineer will ask in a year.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALAny system that simplifies to ship — which is every system — accumulates assumptions; the register's shape and its two trigger moments apply regardless of what is being built.
- TEAM-SPECIFICA solo learner keeps the register in the engineering notebook and the "who would object?" question is mostly about their own future self; a team of several keeps it where the product owner can read it, and promotion to requirements is a conversation rather than a note.
- ILLUSTRATIVEThe store's entries, the neighbouring-country requirement and the retirement text are invented to show the shape and the two moments; the real register for a real store will have different entries and more of them.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The engineering notebook at /thinking/notebook keeps assumptions beside decisions and unknowns for exactly this reason; the decision-journal half of it is where retired entries and their replacements belong.