Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / How a CTO Uses a Trade-Off Log to Make Architectural Decisions Auditable
Transcript
- Lucas: We've all been there. You're in a meeting, someone asks why the system uses PostgreSQL instead of a document store, and nobody remembers. The person who made the call left two years ago, and the rest of the team just shrugs. Luna: It's the default state of institutional knowledge in engineering. It lives in people's heads or in a Slack thread that's already been archived. Lucas: Right. And the cost of that is real — you either re-litigate old decisions or you inherit them blindly. So today I want to talk about a tool that solves this. It's called a trade-off log — sometimes called an Architectural Decision Record, or ADR. But I think 'trade-off log' is more honest about what it actually captures. Luna: Because every architectural decision is a trade-off. You're not picking the perfect solution, you're picking the one that costs the least in the wrong places. Lucas: Exactly. And the log makes that explicit. So the format is simple: each entry has a date, a title, the context — what problem you were solving — then the decision itself, the alternatives considered, the rationale for the choice, and any consequences you anticipate. That's it. One page per decision, stored in a shared repository. Luna: I've seen teams do this as markdown files in the same repo as the code. That way it's version-controlled and sits right next to the thing it describes. Lucas: That's exactly the pattern I want to talk about. A CTO I know at a fintech startup — let's call it PayForward — started doing this about eighteen months ago, and it saved them from a really expensive mistake just last quarter. Luna: What happened? Lucas: So they had built their core transaction engine on a single-node PostgreSQL database. It worked fine for the first two years. But then they started growing fast — transaction volume was doubling every quarter — and the engineering team started talking about sharding the database or moving to a distributed SQL solution like CockroachDB. Luna: That's a huge project. And expensive. Lucas: Massive. We're talking multiple engineering-months, operational complexity, and a migration risk that could take down payment processing. But before they committed, one of the senior engineers suggested they check the trade-off log. And there it was — an entry from three years earlier, written by the founding CTO, documenting exactly why they chose single-node PostgreSQL over a distributed database. Luna: And the rationale was probably something like 'simplicity over scalability' because at the time they didn't need scale. Lucas: More or less. The entry said: 'We are choosing single-node PostgreSQL because it minimizes operational overhead for a team of four engineers. We do not yet need horizontal scalability. If transaction volume exceeds one million per day, we will revisit this decision and evaluate sharding or distributed SQL.' It also listed the alternatives — Cassandra, CockroachDB — and the specific reasons they were rejected. The key line was: the alternative would add fifty percent more ops burden for a capability we don't need yet. Luna: So the log told them: the original decision was made with full awareness of the trade-off. It wasn't an oversight — it was a deliberate bet on simplicity. Lucas: Right. And that changed the conversation. Instead of assuming the old architecture was a mistake, they could ask: has the context changed enough to flip the trade-off? They calculated their current volume — about eight hundred thousand transactions per day — and realized they still hadn't crossed the threshold the original CTO had set. So instead of migrating, they optimized the existing setup: they added connection pooling, tuned some queries, and bought more RAM. Cost them maybe two weeks of work. Luna: And they avoided a multi-month migration that would have added complexity without solving a real problem. That's the whole value of the log right there. Lucas: Yeah, honestly, if today was worth a coffee to you, that's the link — buy me a coffee dot com slash fexingo. Keeps the show ad-free and lets us keep digging into stories like this. Luna: It's a small way to say this kind of conversation matters. And we appreciate it. Lucas: So back to the log. The PayForward story is a perfect example, but it also raises the question: why don't more teams do this? I think the main barrier is that it feels like overhead. Engineers hate writing documentation, especially documentation that doesn't seem urgent. Luna: And the temptation is to say 'we'll write it down when we have time,' which means never. Lucas: Exactly. So the trick is to make the cost of writing the log lower than the cost of not writing it. The CTO I mentioned did two things. First, he made the template dead simple — just five sections, no more than a paragraph each. Second, he tied the log to the code review process. Any architectural decision that affected the database schema or a major dependency had to include a trade-off log entry as part of the pull request. Luna: So it becomes a gate. Not a heavy one, but you can't merge without it. Lucas: Right. And the reviewers are encouraged to challenge the entry — not the decision, but the reasoning. Is the alternative analysis thorough? Are the consequences realistic? That turns the log into a forcing function for better thinking, not just a record. Luna: I like that because it shifts the log from being a historian to being a collaborator. It helps you make the decision better in the moment. Lucas: Absolutely. And the side effect is that over time you build a searchable corpus of why the system is the way it is. New engineers can read through the log and understand the architecture's evolution without having to track down the one person who remembers. Luna: That's huge for onboarding. Instead of two weeks of shadowing, you give someone a document that says 'here are the twenty decisions that define this system.' Lucas: Exactly. And it also prevents the 'we've always done it this way' trap. Because the log shows you that every decision was made at a specific time under specific circumstances. When those circumstances change, you can revisit the decision with full context. Luna: Are there cases where the log can backfire? Like, people use it as a weapon — 'well, the log says we chose X, so we can't change it.' Lucas: That's a real risk. The CTO I talked to was very explicit that the log is not a binding contract. It's a reference, not a rule. You can override any decision if the context has changed. But if you do, you write a new entry that references the old one and explains why the trade-off flipped. Luna: So it's a living document, not a constitution. Lucas: Exactly. And the key is to keep entries short. If an entry is longer than a page, you're probably over-documenting. The goal is to capture the essence — what we decided, why, and what we gave up. That's enough to make the decision auditable five years later. Luna: I've also seen teams use ADRs to document decisions that they ultimately rejected. Like, 'we considered using Kafka for event streaming but decided against it because our event volume was too low.' That way, when someone suggests Kafka next year, you can point to the log and say 'we already looked at that and here's why it didn't fit.' Lucas: That's a great practice. Documenting the alternatives you didn't choose is almost as valuable as documenting the one you did. It prevents the team from repeatedly exploring dead ends. Luna: And it saves time in meetings. Instead of re-litigating the same debate, you just reference the log entry. Lucas: Right. So the question I want to leave with is: what's the one architectural decision in your current system that nobody can explain? That's the one you should log first. Not the newest decision, but the oldest mystery. Luna: And if there's no log entry for it, write one now. Even if the person who made the decision is gone, you can reconstruct the context — what was the problem, what options were available, what trade-offs made sense at the time. Lucas: Exactly. And that act of reconstruction is itself valuable. It forces you to understand the system you're building on. So I'd say: start with one entry this week. See how it feels. Luna: I might do that with our own infrastructure. Because I honestly don't know why we chose this particular CI tool. Lucas: And that's exactly the point.