The State of Assumptions Logs in Engineering Design Notes

The State of Assumptions Logs in Engineering Design Notes

Spend an afternoon reading engineering design documents from different teams and a pattern emerges: the strongest ones have a modest section, usually near the top, where the authors admit what they are guessing. It might be called “Assumptions”, “Open questions” or “What we are betting on”. The name varies; the habit is spreading. This piece looks at where assumptions logs stand in engineering practice, why they keep gaining ground, and what a good entry looks like in a real design note.

Where things stand

Ten years ago, a design document mostly described the solution: boxes, arrows and a rollout date. Reviewers asked whether the design was elegant. Today, reviews more often ask what has to be true for the design to hold. That shift moves attention from the diagram to the unstated conditions around it, and it makes reviews more productive, because a missing condition is easier to spot than a flaw in a drawing.

Several forces push in the same direction. Systems depend on more third-party services, so more of any design rests on facts the team does not control. Teams are spread across time zones, so the reasons behind a choice cannot be passed along over a desk. And incident reviews keep concluding that a decision was sensible given what people believed, but that a belief was never examined.

What a useful entry looks like

Compare two lines from imaginary design notes.

  • “Traffic will be manageable.”
  • “Peak load will not exceed what the current cluster serves on its busiest hour, plus an allowance for the launch campaign. Confidence: medium. Check: read the busiest-hour figure from the metrics store and ask marketing for the expected sign-up volume.”

The second line names a condition, shows how sure the author is, and points to a concrete action. It can be proved wrong, which is exactly what makes it valuable. When it is disproved, the reader knows which part of the design to revisit.

Four categories that keep turning up

  1. Load and growth. Request volumes, data size, the proportion of cache hits, and how quickly any of these change.
  2. Dependencies. Rate limits, uptime of external services, API behaviour under failure, and whether a vendor will keep a feature available.
  3. People and process. Who is on call, who reviews changes, how fast approvals move, which skills the team already has.
  4. Environment. Network latency between regions, the behaviour of the deployment platform, quotas on the cloud account.

Most real logs mix all four. The point is not neat taxonomy but coverage: if a category is empty, ask whether that is because nothing is assumed or because nobody has looked.

A worked engineering example

Suppose a team is designing a checkout service for a regional storefront. The assumptions block might include the following lines.

  • The payment provider’s sandbox mirrors production error codes (low confidence; check by comparing documented codes with a handful of live test transactions).
  • Peak concurrent sessions stay below the connection limit on the database (medium; check with a short load test against a copy).
  • Mobile clients retry failed calls no more than three times (unknown; check by reading the client code or asking the app team).
  • The on-call rota will cover launch weekend (medium; confirm with the team lead and note the answer in the ticket).

Four lines took a few minutes to write. Two of them led to a load test and a conversation that would otherwise have happened in the middle of an incident.

How logs connect to the rest of the toolchain

Teams usually place the log in one of three spots: inside the design document, in the ticket that tracks the work, or in a repository file kept beside the code. Each has trade-offs. A document is easy to read but easy to forget. A ticket links nicely to the work but may be archived. A repository file is versioned and travels with the code, so reviewers see changes to beliefs in the same pull request as changes to behaviour.

Whichever you pick, link to it from wherever people look first. For capacity questions, it helps to read the log alongside a broader piece on coping with traffic surges using current cloud infrastructure; for requirements, an article such as the engineering-focused requirements blueprint for web projects gives you context for what the assumptions are modifying.

How reviewers can use the log

A reviewer who reads the assumptions first often finds the design easier to judge. Start with the lowest-confidence lines and ask three questions: who found this out, when, and what happens to the design if the answer is no? If the author cannot say, that is the review comment. It is a gentler and more precise challenge than “I am not sure this will scale”, because it points at a specific belief rather than at the author’s competence.

During an incident, the same page helps responders. If an alert fires on a dependency, they can scan the log, see that the team had already flagged its limit as unverified, and skip straight to that part of the system. The log becomes a map of known soft spots.

Learning the habit

Engineers pick this up in different ways: from a mentor, from a post-incident review, or from structured courses. Among the many training websites, NoOpsSchool is one India-based example that presents certifications, courses, consulting and services aimed at IT professionals; the site speaks for itself on what it provides. Reading is only half of it, though. The habit sticks when you attach it to a live design and are forced to defend each line to a reviewer.

Where logs go wrong

  • Vagueness. “The system will scale” cannot be checked. Name a quantity, a service or a date.
  • Orphaned entries. If no one owns a line, no one verifies it. Put a role beside every unknown.
  • One-time writing. Logs that are never revisited become comforting fiction.
  • Overload. Twenty weak lines bury the three that matter; trim ruthlessly.

Where this is likely heading

Expect assumption sections to become standard in design templates, ticket forms and review checklists. Some teams already require a reviewer to challenge at least one low-confidence line before approving a design. Others add a short retrospective step: once a project ships, mark each assumption as held, failed or untested, and keep the tally with the design record.

None of this is glamorous. It is a bit of writing discipline that makes decisions legible. For a profession that spends so much effort on tooling, the humble list of beliefs may be among the highest-return practices available.

Getting started this week

Pick one design you are working on. Add a heading called Assumptions, write five lines, and mark each with confidence and a check. Share it with a reviewer and ask for one more line you missed. Next sprint, mark which beliefs held. That is the entire experiment, and it will tell you quickly whether the practice fits your team.