Assumptions: Writing Down What Has to Be True

Every spec rests on things nobody has checked. The data is already there. Admins are the ones who set this up. The partner API returns that field. Users who hit the error will see the banner.

Written as facts, they do not invite a check, and an unchecked assumption is the kind of thing that fails after launch rather than before it.

There is one question that finds them: what would have to be true for this to be a mistake? It is the fix we proposed for the well-formed wrong thing, and one of the three questions a person should ask after an automated review comes back clean. Asked in a meeting, it gets one thoughtful answer and is forgotten by the next agenda item. Written into the spec as a section, it gets an owner and a date.

From question to list

Run it backwards. Imagine the feature shipped and turned out to be a mistake, then list the reasons it could have been. Each reason, turned the right way up, is an assumption.

To make sure you cover the whole spec rather than the part you were last thinking about, go section by section:

• Problem. That it happens as often as the statement says, to the people it names. A problem statement that survives review makes this easier, because the frequency and its definition are already written down.
• User. That the person who has the problem is the person who will use the fix.
• Solution. That this addresses the cause rather than a symptom, and that people will find it at the moment they need it.
• Data and systems. That the data exists, is accurate enough, and can be reached by this feature.
• Dependencies. That another team, vendor or system will do its part when you need it. These are the dependencies people forget to write down.
• Measurement. That the event you plan to count is emitted, and means what you think. A metric with no baseline usually hides an assumption here.

Which ones make the cut

Two filters. Keep an assumption only if being wrong would change the plan, and you do not already know the answer.

Things that fail the filters:

• "Users will like it." Too vague to check. Which users, liking it how, measured by what?
• "Assumes normal usage patterns." Normal by what measure? The Lean PRD template lists it as one of the ways the section fails, for that reason.
• "The team has capacity this quarter." A real risk, but a planning one. It does not change what the spec should say.
• "Exports are in CSV." You decided that. It is a requirement, not an assumption.

What is left is usually a short list. If it runs past a page, some of those lines are fears rather than premises; keep the ones that would change the plan.

The section

An illustration, for a feature that helps admins set the right permissions on new projects:

Assumption	Status	If it is wrong	How we will know	Owner, by when
Admins, not project leads, set permissions on new projects	Believed: 4 of 5 interviews	The flow is built for the wrong role	Query who made the first permission change on August's new projects	PM, before design review
The permissions API exposes inherited permissions	Unknown	The inheritance preview cannot be built; scope drops	One-day spike	Eng lead, sprint 1
The clean-up cost comes from wrong settings, not from the sharing model	Believed: inferred from tickets	Fewer mistakes, same clean-up time; the metric does not move	Compare re-share events on beta accounts	PM, beta week 2
Permission changes are logged for every project type	Verified for standard projects; unknown for templates	The success metric undercounts	Ask the data team	Data, before launch

Three columns do most of the work.

Status uses three words: verified (with a source), believed (with the basis), unknown. The basis matters as much as the label; "4 of 5 interviews" carries the same information an evidence section would, in a few words.

If it is wrong names the consequence. This is what lets a reader rank the list. An assumption whose failure costs a day is a footnote; one whose failure means building for the wrong role is the first thing to check.

How we will know turns a worry into a task. If nobody can say how the assumption would be tested, that is worth recording too, because it means the first release is the test.

Put the section near the top, after the problem and scope and before the requirements. An assumption that could change who the feature is for is a constraint, and a constraint read on page six arrives after the reader has already pictured the solution. It helps the author too: requirements written underneath a visible list of unknowns make it obvious which of them are resting on a guess.

Write the stop condition before the result

For the one or two assumptions the whole plan leans on, add a line saying what result would change or stop the plan, and write it before you have the result.

Our briefing on a placebo-controlled study of AI code repair shows both halves of why. The author wrote down a success rule before running anything, then reported plainly that it was not met. And the idea's precondition, a failing test that could point at the bug, held for only 9.0% of the failing programs; the rest had no failing public test with usable coverage data to point from. Ask how often the precondition holds before asking whether the idea works.

A spec can make the same move in one sentence: "If fewer than half of first permission changes are made by admins, we redesign the entry point before building the flow."

Keep the section alive

Assumptions change status during the build. When one is verified, update the row and link the source. When one breaks, it is a decision point, not a footnote: decide what changes and record it where the reasoning will outlast the spec.

In review, the most useful question about this section is a short one: which of these, if wrong, would you want to know about before we start? Then order the first week so those get checked first.

A note on generated drafts

A good AI drafting tool should separate what you told it from what it assumed. The test we suggest for evaluating a PRD generator includes exactly this: does the draft write "Assumption: workspace admins only, confirm", or does it state its guess in the same voice as your facts? A draft that marks its assumptions has handed you the start of this section. One that does not has hidden it inside the requirements.

FAQ

What is an assumptions section? The unverified things the plan needs to be true, each with a status, a consequence and a check.

How do I find them? Ask what would make this a mistake, section by section.

Which belong? Ones that would change the plan, and that you do not already know.

"Assumptions: none"? Means nobody looked.