Dictating architecture decision records: the context your branch history erases

Every architecture decision is obvious while it is being made and mysterious six weeks later. The team chose the event bus over the direct call, accepted the cache-over-consistency trade, and nodded at the single-writer table that everyone privately doubted, and then the meeting dissolved into feature work, and the context evaporated with it. The comment in the code, once there is one, says why the line exists, but never why the whole shape was chosen, and the next quarter somebody reads the shape, finds it odd, and reopens the debate they were not present for. This is exactly what an architecture decision record exists to prevent, and the reason most ADRs never get written is that writing one after the fact means reconstructing context nobody remembers, which is why dictating architecture decision records before the first commit is the version of the habit that survives a realistic week.

The standard advice is to write the ADR, which is sound and also unhelpful, because the moment that is available to you, the decision meeting, is exactly the moment you are too busy deciding to write anything. The trick is the medium: an ADR can be spoken in the meeting, in real time, without taking your hands out of the debate. When you say: let me capture this, and we should note the trade is cache freshness against load, the room hears the decision being recorded, the argument gets sharpened, and the record exists before the code does. A voice-captured, then cleaned-up ADR is the only kind that reliably gets written, because drafting by dictation costs nothing in the heat of the room.

The second reason ADRs die is the audience problem. A typed ADR is a document nobody asked for, and documents are read only in times of emergency. A dictated ADR, however, is a spoken record that can be distributed as a note, a clip, or a short summary with the audio attached, and people listen to a ninety-second recording. The meeting minutes get skimmed, but the code author's own voice, deciding the trade-off on the day, carries the intent in a way that survives. This is the whole reason the tape format wins: intent is a spoken thing, and no paraphrase reconstructs it faithfully.

There is a strong practical reason to do this before the first commit rather than after: the decision that gets recorded before code is the decision that stays a choice, while the decision recorded after code is already locked by the implementation. Dictating the ADR first also changes how you code the feature, because you have just said out loud what you are not going to do, and the code you then write respects the boundary instead of quietly drifting over it. The tape is not bureaucracy; it is a fence around scope, and the fence saves you the re-litigation that otherwise starts, predictably, four weeks after merge.

An ADR that only records the winner is a memoir, so before you record the choice, name three options out loud and their trade-offs. Three is the operative number, because one option is not a decision, two options is a fight, and three options is a conversation. Say them plainly: option one, the direct call, simple and fast, but we own retries; option two, the event bus, decoupled and inspectable, but we own the delivery failure surfaces; option three, the stored job table, gives us a durable queue, but asks a scheduler. Each sentence is one option plus its strongest cost, and that format is exactly what the ADR needs later.

Explain, out loud, why the other two lose. This is the part every ADR omits and the part that stops the re-litigation, because the next engineer does not need your winner, they need your elimination order. Say: the direct call loses because a customer offline destroys the job, and the event bus loses because our team already runs a bus we do not monitor, so the queue wins. Hearing yourself say why two good options lost is also a check on your own bias, because a trade-off that dies for a weak reason is revealed the moment you have to defend it in a sentence. If you cannot say why the loser loses, you have not decided; you have picked a favorite.

Ask the skeptical questions out loud too, with the option names: what would make the direct call win for us? If we never have offline customers, it wins. What does the bus assume about the monitor we do not have? This is the Socratic pass that catches the hidden assumption, and it costs two minutes of speaking while the team is present. Most ADRs are written by the team that decided and read by a team that did not, and the skeptical questions are the only channel through which unspoken assumptions travel. When you ask them aloud, the answers go into the record, and the record stops being a verdict and becomes an argument, which is what it has to be to survive.

Time-box the options conversation, then choose out loud with a finish line: we are going with the stored job table, because durability outweighs the scheduler cost for this feature. Announcing the choice aloud to the room gives everyone a chance to object in the moment, where objections are cheap, instead of in the review, where they are expensive. Then immediately say who is bound by it and for how long: this binds the pipeline team until the next version of the queue work, six months. An ADR without a horizon invites both eternal reverence and abrupt abandonment, while a horizon lets the team agree that the decision is a lease, not a life sentence.

The decision tape needs four beats to be useful, and they are the same four beats you would give a teammate who just joined the team. First, the context: what changed in the last quarter that made this decision necessary, in one or two sentences. Second, the options and the eliminations you already named. Third, the choice itself, stated as a sentence a new engineer can quote. Fourth, and this is the beat everyone forgets, the consequences: what we accept is less convenient, what we invited in, and what has to change if a consequence becomes unacceptable. Dictating all four while the meeting is warm is the entire craft, and the four beats take about two minutes of speech.

The consequences beat deserves special care because it is the one that makes an ADR honest. Say: the cost we accept is that job state is invisible to support for the next two weeks, because the admin UI does not show the queue yet. A single sentence about an accepted cost is worth more than a page of rationale, because it tells the next reader that you saw the downside and went in anyway, and it tells the team exactly which complaints are anticipated and planned rather than reportable bugs. Dictate the cost in the same words you used when you argued against the other options, since the purist in the room was right about something and your record should show that something.

Then dictate the revisit triggers explicitly: we revisit this when the queue grows past ten thousand jobs a day, or when the admin UI ships, or when someone proposes a second queue for the export path. Triggers are the difference between an ADR that survives and an ADR that gets ignored, because they give the team permission to change the decision without fighting it, and they pre-empt the silent migration that happens in the worst case, the one where the system drifts to a hybrid shape and nobody can say why. A spoken trigger list is also a maintenance budget: it tells future you when this tape needs updating, rather than leaving the record to rot quietly.

Finish the dictation with the same sentence every ADR should end on: if this decision proves wrong, the cost of reversing it will be this, and that is a cost we have already priced in. Pricing the reversal is the most senior thing in the entire record, because it removes the shame from changing your mind later, and it tells the team that you did not choose the reversible option out of cowardice. Dictate the reversal cost even when it sounds scary, since a decision that everyone is afraid to revisit is not a good decision, it is a hostage situation. Once the four beats are taped, have the assistant turn the recording into the ADR document, add the date and the names, and commit it with the very first line of code.

An ADR that is never checked is a monument, not a tool, so put the check on the calendar for six weeks after the commit: open the record, open the current implementation, and say out loud whether they still agree. The disagreement is rarely a full betrayal; it is usually a drift in a small spot, like a job table that grew a second retry loop nobody recorded, or the queue key that changed shape but the ADR still describes the old one. Reading both aloud in the same breath makes the drift audible, and catching a drift at six weeks costs a comment instead of the archaeology it would cost at six months.

The check is also a test of the record's usefulness. If you cannot navigate your own decision from the ADR in five minutes, the record failed its job, because it was written for the person who reads it in an emergency, not for the person who wrote it. Say the five-minute test out loud: from my ADR, what is the queue's failure semantics? If the answer needs a code read, the tape is being lip-synced by the document. Fix the record while you are here, since a document that is already wrong is worse than a missing one: it gives the next reader false confidence, and false confidence in architecture is how the worst decisions get inherited.

Look for the consequences you dictated, and see whether they arrived as predicted. The admin UI gap that cost the support team two weeks: did it actually cost that? Did the queue really never grow past the threshold you set? Speaking the forecast against the reality is the most useful part of the check, because it turns your own past record into training data for the next decision: you picked the durability option, and the durability never got tested, so the honest note in the ADR is that the deciding trade never materialized and the runner-up might have been fine. Records get better when they admit that their forecast was boring.

Then decide out loud what the record becomes: stays as is, gets a revision note, or gets superseded. Say the sentence: this decision holds, the queue stays, but we now need the admin UI and I am adding that as a follow-up. If the decision is superseded, do not edit the old record; write a new one that says why and links back, because the history is the thing you want. A superseded ADR that still exists, saying its successor's name, is a whole museum of the team's thinking, and the museum is the best onboarding material an architecture practice can leave behind, particularly for the new hires who join in week seven and inherit the queue problem at full force.

The ADR that gets read is the one that fits in ninety seconds, so when the tape becomes a document, force it into shape: status, date, context in one paragraph, the three options in a table where each row lists the option and its cost, decision in one bold sentence, and consequences plus triggers in a bullet list. That skeleton is shorter than the recording and it is exactly what a busy engineer will actually open. Dictate the conversion instructions to the assistant rather than writing the document yourself, and keep the spoken language, because a translated-to-formal ADR loses the voice that carries the intent, while an ADR that reads the way the team talks gets read by the team.

The first draft conversion loses details, so do a readback: read the generated ADR aloud and compare it against the tape. Where the document and the recording diverge, that is your signal that the deciding argument was oral in nature. Keep the decisive phrases from your own voice, since the phrase the queue loses on the cold start, said on the day of the decision, was the phrase that convinced the room, and it will still convince the room a year later about what the trade-off actually was. Reading aloud also catches the polite rewrite, where the drafting made the record nicer than the decision, and niceness is a leak: the next team will be surprised when the nasty cost arrives and the ADR never mentioned it.

Distribute the ADR as a note in the team channel with the recording attached, or as a short spoken summary with a link, because a decision nobody saw is a decision the team will re-open. Add one line to the note: read this if your work touches the queue, and if you disagree, reply in the thread before Thursday. The deadline converts a monologue into a conversation, and the conversation is what makes the record a team artifact instead of an archive. When someone replies with a real objection, record the exchange, and append the resolution to the ADR, since teams that argue on the record stop arguing in the dark.

Keep the ritual alive by attaching it to the first commit every time: tape the four beats, convert, read back, publish, commit. Five actions, twenty minutes, and the record is in place before the code exists, which is the entire point, since the alternative, the undocumented architecture that everyone half-remembers, is the single most expensive recurring cost in a growing codebase. The first time you reuse an old ADR to answer a design question in a review, you will feel the payoff: five minutes instead of a meeting, and the team's own voice, still on tape, settling the argument that would otherwise have been settled by whoever was loudest that day.