Part II · Chapter 2 · One Service · lesson 8

Say what would change your mind, before you look at options

12 min

Two engineers, four weeks, two documents, no decision. The feature is an activity feed. One document says put it in a new table in the existing Postgres. The other says stand it up as its own service with its own store.

Both documents are good. Both are about options. Neither one says what the decision is supposed to achieve.

What would actually end this argument? Pick before you read on.

Predict

Two well-argued documents, four weeks, no decision. What ends it?

More data — a forecast of volume everyone can agree onSomebody senior picking one, so the team can moveWriting down, before looking at either option, the one thing being optimised and the observation that would reverse the choiceA two-week spike that builds both and measures them

Four lines. That is the whole artefact.

The criterion. One sentence naming the single thing this decision optimises. If it has an "and" in it, you have two criteria and they will conflict later.

The choice. What you are doing, in a sentence.

What would change your mind. Two or three observations, each with a number or a crossing attached, that would reverse the choice. Not "if it becomes a problem" — a threshold somebody could check without asking you.

Who owns it and when it gets looked at again. A date, and a name.

The third line is the one that does the work, and it is the one people leave out. Without it a decision is a preference with paragraphs; with it, a decision is a prediction, and predictions can be checked.

What would you do

A five-person team owns a working product on one Postgres database. The activity feed is the next feature; a pilot customer has been promised it this quarter. The feed shows a user the recent actions of people they follow, newest first, perhaps fifty items a page.

Nobody has written the queries yet. Nobody has instrumented the events that would feed it, so the write rate is a guess. The forecast in the deck is for twenty times the current user count within two years, and the same deck has been wrong before in both directions.

Optimising for: Getting the pilot customer using the activity feed within six weeks, while keeping the store choice cheap to reverse afterwards.
You cannot know: What the real write rate will be, since the events are not instrumented yet
Whether the feed reads are per-follower fan-out or a single global timeline
Whether the growth forecast in the deck bears any relation to what happens
Whether this team still owns the feed in a year, or another team does
How much of the read load a cache would absorb, which nobody has estimated

One new table in the existing Postgres, with every read and write of the feed behind a single module that nothing else reaches past.A separate feed service with its own database, decided now, on the grounds that extracting it later is harder than starting that way.Add a document store alongside Postgres, because a feed item is a denormalised document and that is the natural shape for it.Spend two weeks building both against synthetic load at the forecast volume, and decide on the measurements.

What I would actually write, and where

One page, in the repository, as a numbered decision record — docs/adr/0007-activity-feed-storage.md, MADR template or anything with the same four headings. Not a wiki, because a wiki page is not reviewed with the change it describes.

The part worth copying is the third heading, because it is the one that is usually a shrug. Here it is written properly for this decision:

What would change our minds. We move the feed to its own store if any one of these holds: sustained feed writes pass two thousand rows a second for a week; the feed table passes five hundred million rows; feed inserts appear in the top three statements by total execution time on the primary; or a second team needs to deploy feed changes without deploying this service. Reviewed at the next quarterly planning session by whoever owns this service.

Four triggers, each one checkable by somebody who was not in the discussion, three of them with a number. That is the difference between a decision and an opinion: six months from now nobody has to reconstruct the reasoning, they just have to look.

And the triggers do a second job nobody expects. They tell you what to instrument. Two of those four require a measurement that does not currently exist, so writing the record produced a small amount of real work — and a team that cannot check its own reversal triggers has not actually made a reversible decision.

Check

Which of these is a usable 'what would change my mind' line?

If the feed becomes a performance problem for the main serviceIf feed inserts appear in the top three statements by total execution time on the primary for two consecutive weeksIf the team decides the architecture no longer fitsIf we grow twenty times, as the forecast says

When writing the criterion does not help

The condition under which this whole method stops working: when the criterion itself is what the argument is about.

Sometimes the two documents are not two answers to one question. They are two different questions, held by two people with different jobs. One is optimising for a pilot customer this quarter; the other is optimising for not being the person who has to extract a feature under pressure in eighteen months, having done it before. Writing a criterion does not reconcile those. It makes them visible, which is not the same thing.

What to do then is specific, and it is not a technical move. Write both criteria down, side by side, with the option each one selects. Then take the pair to whoever owns the outcome they disagree about — because the question "which of these two things are we optimising for this quarter" belongs to whoever owns the quarter, and two engineers cannot settle it by arguing about databases for another four weeks.

That is still a win. An argument that was about Postgres for a month becomes a ten-minute conversation about priorities, with a written record of what each priority implies. And the criterion that comes back is the one you put at the top of the decision record, attributed.

Worth remembering

An architecture argument that has lasted weeks is usually not short of facts; it is short of a shared statement of what the facts are for.
Write the criterion before looking at the options — written afterwards it is a rationalisation of a preference rather than a filter.
A criterion with an 'and' in it is two criteria, and they will conflict at the worst moment.
The four lines of a decision record: the criterion, the choice, what would change your mind, and who revisits it when.
A reversal trigger must be checkable by somebody who was not in the room — 'if it becomes a performance problem' hands the same argument to the future with less context.
Good triggers name a threshold and a duration, so one busy afternoon does not fire them.
Writing the triggers tells you what to instrument: a team that cannot check its own triggers has not made a reversible decision.
When the two sides disagree about the criterion rather than the options, the decision belongs to whoever owns the goal — writing both criteria down surfaces that instead of settling it, which is still most of the value.