Unknown Unknowns
The board lists what you know you do not know. The unknowns that hurt are the ones not on it — and there are moves that surface them: asking what the experts in this area worry about, walking the failure paths, reading a real system's incident history, and listening for the word "just".
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.
Your unknowns board is written. How do you find the unknowns that are not on it — the ones you do not know enough to ask about?
The checkout board is thorough: payments, double submit, stock. You build it, it works in test mode, and on the first real day a customer's bank declines the charge after the order was created, a refund is requested for an order that was never paid, and the provider's dashboard shows a "dispute" you have never heard of. None of these was on the board because you did not know they existed.
Accept it as the nature of unknowns: you cannot list what you do not know, so you ship and learn from production. It feels like humility, and it is partly right.
The lesson is learned per incident, in production, at the highest possible cost, and the next feature's board is just as blind because the method did not change.
- The lesson is learned per incident, in production, at the highest possible cost, and the next feature's board is just as blind because the method did not change.
- "Learn from production" becomes a reason not to look for the things that could have been found in an hour. Declined payments are in the first paragraph of every provider's guide; disputes are in the second.
- The board's thoroughness becomes a false signal. Because everything on it was answered, the feature felt complete, and the gap between "everything I asked" and "everything there is" was invisible.
- The team stops trusting boards, and the reaction is to stop writing them — which loses the known unknowns too.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Accept that the board is bounded by your vocabulary, then borrow other people's. The question is not "what don't I know?" — which you cannot answer — but "what do people who have built this worry about?", which they can. Provider documentation, a colleague who did the last integration, incident write-ups, and the failure sections of a domain lesson are all vocabularies larger than yours.
- Walk the workflow asking "and then what?" at every step, especially the steps after the happy path ends. Order created — and then what if the payment is declined? Paid — and then what if the customer wants it back? Each "and then" that you cannot answer is an unknown that was hiding behind a success.
- Listen for "just" and "obviously" in your own plan. "We just mark it paid when the webhook arrives" contains a verb you have not examined — mark it paid — and every unexamined verb is a place where an unknown lives.
- Ask what the domain's nouns are that you have not used. Payments has authorisation, capture, refund, chargeback, dispute, settlement. You do not have to handle them all in V1, but the ones you have never heard of are the ones that will arrive unannounced; knowing the noun exists is what lets you put it in "not V1" on purpose (What Can I Ignore for Now?).
Where the missing unknowns come from
Four sources, each a vocabulary larger than yours. The decision is which to consult first, and that depends on what kind of unknown you are missing — the ones about an external system live in its documentation; the ones about your own workflow live in the walk.
My board feels complete. Where are the unknowns I have not asked?
when The unknowns are about a provider, a protocol, a library — anything with documented states or events.
cost An hour reading the vocabulary section. Produces nouns; most go in "not V1".
when A colleague or a write-up exists. Ask "what surprised you?"
cost A conversation. Produces the surprises directly, with the cost already paid by someone else.
when The unknowns are about your own workflow — orders, stock, admin — where no documentation exists.
cost Half an hour per workflow. Produces the failure paths, which then go to Failure-First Questions.
when You have a written plan. Every "just" hides a verb.
cost Minutes. Produces the unknowns you already had and had hidden from yourself.
The walk, written out
The "and then what?" walk on checkout, as a board. Each unknown found is sharpened on the spot, because an unknown unknown that is discovered and left vague has only moved columns.
- ✓Order created from cart with status pending; paid on the verified webhook, keyed on event id.
- ✓Payment initiated server-side; the redirect renders and decides nothing.
- ~Refunds are handled by hand in the provider dashboard in V1 — a decision, now that the noun is known.
? And then what if the payment is declined?
becomes How long does a pending order hold its stock, and which component releases it when payment does not arrive?
experiment Create an order, never pay, and watch what the stock table shows an hour later — it shows the bug before the bug is a customer.
? And then what if a dispute arrives?
becomes When the provider reports a dispute on a paid order, what state does the order enter and who is told?
experiment Trigger a test dispute in the provider's sandbox; confirm the event reaches the handler and is logged and alerted rather than dropped.
? "We just mark it paid."
becomes What stops a forged webhook from marking an order paid?
experiment POST a hand-written event to the handler without a signature; it must be rejected — see the backend lesson on signature verification.
Three unknowns from one walk, none of which was on the thorough board. Two are handled in V1 and one is a documented "not yet".
The state machine you did not know you had
Borrowed vocabulary often arrives as a lifecycle, and drawing it is the fastest way to see which states your system has no answer for. The diagram is the payment lifecycle as the provider describes it, with the two states V1 handles marked and the others routed to a single "log and alert" — a design, rather than an absence.
How to do it
Most important first.
- For each external system, read the section of its documentation titled something like "lifecycle", "states" or "events" — the vocabulary list — before the quick-start.
- Walk the core workflow and write "and then what if…" after every step. Stop only when the answer is "nothing — the workflow is over".
- Find someone who has built this and ask "what surprised you?", not "how does it work?". The surprises are the unknown unknowns, pre-discovered.
- Scan your own plan for "just", "simply" and "obviously"; write the verb that follows each on the board as an unknown to sharpen.
- Put the discovered nouns in the right column: some become questions, most become "not V1, on purpose". The value is in knowing they exist.
Worked on a concrete problem
The move has to produce something. This is what it produced.
- The provider's events page lists: created, requires action, authorised, captured, failed, refunded, disputed, dispute closed. The V1 board had used two of those words. Three of the others became "not V1, by decision, and here is what we do if one arrives: log it and alert" — which is a design, whereas ignorance was not.
- "And then what?" applied to checkout: order created → payment declined → and then what? The order sits at "pending" forever; the stock stays reserved. Unknown found: how long does an unpaid order hold stock, and who releases it? That became a founder question and a timeout, before the first real customer rather than after.
- "We just mark it paid when the webhook arrives." Examined: the webhook could be forged (signature verification — an unknown), could arrive for an order we do not have (ordering — an unknown), could arrive twice (idempotency — already on the board). Two new unknowns from one "just".
How you know it worked
What now exists that did not before, and what question you can now ask.
- The board contains nouns you learned this week, and most of them are in a "not V1" list with a reason and a fallback.
- Every step of the workflow has an "and then what if" answer, even if the answer is "log and alert".
- Your plan has no "just" left in it that you have not examined.
- The first surprise from production is something no vocabulary you consulted contained — a genuinely new unknown, not one from the first paragraph of the guide.
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.
- ?What do people who have built this worry about that I have not mentioned?
- ?After each step of the workflow — and then what, if it goes wrong?
- ?What are the nouns of this domain that I have never used, and which am I ignoring on purpose?
- ?Where have I said "just"?
What can go wrong
- The search for unknown unknowns never ends. Every noun spawns a question; every "and then what?" goes another level; the board is complete and V1 is not started. The bound is the workflow: walk it once, list the nouns once, and put most of them in "not V1".
- Every discovered noun is handled. Disputes get a full workflow in V1 because they were discovered. Discovery is for deciding, and most decisions are "log it, alert, handle by hand" (What Is Not V1).
- Borrowed vocabulary is trusted over your own workflow. The provider's lifecycle has fifteen states; your store needs four. Learn the fifteen so you can choose the four, not so you can model all of them.
- The move is applied only to external systems. Your own inventory, your own refunds, your own admin actions have unknown unknowns too, and no documentation lists them — the "and then what?" walk is the only tool there.
- An hour of vocabulary reading before the quick-start delays the first line of code — and on a domain you know, it is wasted.
- Discovered unknowns lengthen the "not V1" list and the conversation with the founder about it. The alternative was a shorter conversation and a longer first week in production.
- Some unknown unknowns can only be found in production. The move reduces the set; it does not empty it, and a team that expects it to will be disappointed at the first genuinely new surprise.
- "So I should read all of the provider's documentation." No — the lifecycle or events section, which is short and is the vocabulary. The rest is answered when a specific question sends you to it.
- "Unknown unknowns are unfindable by definition." They are unfindable by introspection. They are findable by borrowing someone else's vocabulary, which is what the move does.
- "This is failure modeling." It overlaps: the "and then what?" walk is the entry to Failure Modeling. This lesson is about noticing that the question needed asking; that module is about answering it.
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.
- GENERALBorrowed vocabulary, the "and then what?" walk and the search for "just" apply to any system with an external dependency or a lifecycle — which is every system.
- DOMAIN-SPECIFICIn payments and anything regulated, the unknown unknowns carry legal and financial cost and the vocabulary reading is not optional; in an internal dashboard the same walk takes ten minutes and most discovered nouns can be safely ignored forever.
- ILLUSTRATIVEThe provider's event list, the disputed charge on the first day and the fifteen lifecycle states are invented to show the shape of the move; read the real provider's list.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto's /manifesto/without-ai page argues that unknown unknowns are exactly what an AI-generated integration hides best: the code handles the states the prompt mentioned, and the prompt mentioned the states you knew.