Revisiting Assumptions at the Eight-Month Mark

Every system I ship starts with assumptions. Eight months later, most of them are wrong. Not in a dramatic way, just drifted from reality. A quarterly ritual of listing assumptions and testing them against the live system has saved me more than any other practice this year.

What an Assumption Looks Like

'Users rarely create more than ten posts per day.' 'The newsletter list will stay under a thousand subscribers this year.' 'Images are always under 2MB.' Each is a silent design decision: query limits, SES tier, no image resizing. Each is fine until it is not.

The problem is that assumptions get buried in implementation details. No one wrote them down. No one checks them. Reality drifts and the system quietly strains.

The Assumptions Ledger

I keep a file called ASSUMPTIONS.md in every project. One line per assumption, with the date recorded and the design choice it drove.

plaintext

2025-04-10: users create &lt;=10 posts/day -> query limit 50
2025-04-10: newsletter list &lt;1000 -> SES sandbox fine
2025-05-02: images &lt;2MB -> no resize pipeline
2025-07-18: slugs unique per user -> no global index

Quarterly, I open this file and run the real numbers. Which assumptions still hold? Which are within 20 percent of breaking? Which have quietly broken already?

The Measurement Query

For each assumption, a one-line query answers whether reality still matches:

plaintext

aws logs filter '| stats max(posts_per_day) as p95'
aws ses get-send-quota
aws s3 ls s3://media --summarize   # check size distribution

If the answer is near the threshold, I schedule a fix before the threshold breaks. If the answer is far from the threshold, the assumption still holds and I move on.

Why This Matters More Than Postmortems

Postmortems fire after an outage. Assumption reviews fire before one. The cost of a quarterly review is thirty minutes. The cost of the outage it prevented is usually much larger. See NIST's risk management guide for the general framework: list, measure, mitigate, repeat.

The Biggest Assumption I Missed

I assumed the site would stay English-only. By month six, two clients asked about multilingual support. That assumption shaped the slug schema, the content model, and the URL structure. Unwinding it was expensive. Writing it down on day one would have cost nothing.

Every assumption is a future bill. Pay small, regular installments on review instead of lump sums during outages.

Writing Assumptions at Decision Time

The discipline I added this year is recording the assumption in the same commit as the design choice it drove. One line in the commit message: 'assumption: X'. When I search git history six months later, the assumption sits next to the code it shaped. No separate file to forget. Combined with the quarterly review, this turns implicit capacity limits into an audit trail the whole team can read. The overhead is one extra line per commit; the payoff is compounding clarity.