When Peat Bakke sits down for breakfast with engineering leaders, the conversation inevitably turns to the same frustrating pattern: talented people leave, and with them goes critical context about why systems work the way they do. Not just the technical details—those live in the code—but the reasoning behind architectural and technical choices, the problems those choices solved, and crucially, the alternatives that were deliberately rejected.

This isn’t a staffing problem masquerading as an administrative documentation problem. It’s an organizational memory problem that compounds as companies grow. As Peat explains, “What you didn’t decide to do—that’s the organizational lore that gets lost when people move around.”

The solution isn’t just writing more things down. Decision records only create value when they’re accessible, digestible, and tied directly to the tools teams use every day. The most effective organizations treat decision context as infrastructure, not paperwork. They understand that the goal isn’t comprehensive documentation—it’s ensuring that when someone inevitably gets “called in when a company is going through hypergrowth” or when they need to “reduce expenditures in painful ways,” the reasoning behind past choices is available to inform new ones.

In a follow-on from Chris Swan and Thomas Dullien’s conversation in our last episode of Velocity’s Edge, Peat and host Nick Selby explore how to build decision records that actually help teams move faster rather than creating bureaucratic overhead. They tackle essential questions: How do you determine when a decision is significant enough to document? What’s the “after-the-fact test” that reveals whether your documentation is genuinely useful? How can AI help make years of accumulated decision records searchable and actionable without introducing hallucinations into critical business decisions?

Nick and Peat discuss a fundamental truth: the companies that scale successfully aren’t those that document everything; they’re the companies that capture decision context so future teams can make informed choices about what to change and what to preserve.

Peat Bakke is a seasoned engineering leader with more than 25 years of experience helping companies navigate significant transitions, including reorganizations, mergers and acquisitions, hypergrowth, and cloud migrations. He has held senior engineering roles at eBay, Kickstarter, and Peek, where he led a team of 70 engineers through a Series C funding round. Peat is the founder of Refactor Management, specializing in helping engineering leaders build high-performance teams through systems thinking and psychological safety.

As in all our episodes, we speak in plain, executive-summary business terms, framing complex business and technology strategic challenges in context, using language that makes them more accessible and actionable.

Listen here, download it from Apple Podcasts, Spotify, or find it wherever you get your podcasts.

Episode Information
Season 1, Episode 7
Length: 16 minutes, 53 seconds
Host: Nick Selby
Guest: Peat Bakke
Recorded: VOXPOD Podcast Studios, Parsons Green, London
Engineer: Dayna Ruka
Editor: Dayna Ruka, Jeet Vasani

Episode Transcript

Nick Selby: It’s Velocity’s Edge podcast. I’m Nick Selby and I’m here today with Peat Bakke. Peat, can you introduce yourself, please?

Peat Bakke: You bet. Pleasure to be here. My background: I’ve been working in tech for over 25 years; started as a lowly intern and developer, and for the last several years I’ve been working with VCs, PEs, investors, mergers and acquisitions, helping companies get through the thorny stuff– particularly related to engineering teams. I get called in when a company is going through hypergrowth. I also get called in when they reach the end of the runway and they need to figure out, “How do we reduce expenditures in painful ways?”

NS: Oh man.

PB: Yep. That’s what I do.

NS: Peat and I met about five years ago when he was at a company as the head of engineering, and I was a consultant brought in for something. And we’ve remained friends and we’ve talked, I would say, quasi-regularly.

A couple of weeks ago, I was in Portland, Oregon, where Peat is based, and we were sitting down having breakfast and (yes, I know it’s a bad conversation), we were actually talking about decision records. I was mentioning the episode that just aired last week with Chris Swan and Thomas Dullien. And Peat, you started saying some really interesting things about how you use decision records. So I asked you immediately if you could come on to do a part two for that episode. Thank you so much for being here. I really appreciate it.

PB: Yeah. You bet. Yeah. It’s funny. With decision records, the biggest challenge with… the whole reason for decision records is because companies are volatile. People move around. They come, they go. Even in my business with startups, companies come and go. So documentation is critical.

One of the biggest challenges that I have is, during these times of volatility, how do you keep people aligned? How do you help information carry over between teams, between people, between managers? But, focusing on the engineering side of things, how do you do continuity? And that’s what the decision records are all about.

NS: Yeah, I totally agree. I mentioned to you my son is a blacksmith. He makes knives. Over the past eight or 10 years he’s made hundreds, if not thousands, of knives. It’s kind of a fun thing to do at home: I just take out one of the knives that he made a long time ago, and I show it to him. And instantly he’s able to just look at it and start to describe the sacrifices and the changes that he made in order to get from his idea to the finished product. And he’s able to say the trade-offs that he engaged in.

That’s kind of what we’re talking about here, on a much larger scale, because there’s so many more details, and it’s much more complex.

He and I were discussing tech debt, and I mentioned the decision records. We realized that for a small company, or for just one person, it probably doesn’t make a lot of sense. But I think what you’ve said is that you reach a time where you just can’t get away with that anymore. So maybe I can just use that as my first question to you.

PB: Yeah, absolutely. When it’s a couple of guys in a garage building things, it’s not hard to remember, because everyone is there for all the decisions. You’ve been present. It gets more complicated when you start hiring more people, or when you get absorbed into a different company or, whatever it is. There’s all sorts of circumstances that can cause this kind of split in understanding.

NS: Yeah. Gaps in comprehension or gaps in memory. “Why did we do this? How did we end up here?”

PB: Exactly. Yeah. And, “What did we decide not to do?” That’s the other part of it. It’s not just, “What did we decide to do?” Because that’s usually enshrined in a specification or in your source code. What you did decide to do is there. What you didn’t decide to do– that’s the more interesting stuff. Or why you decided to do what you did.

NS: Oh yeah.

PB: That’s the organizational lore that gets lost when people move around. That’s where the value of ADRs really shines.

NS: It’s funny that you say that, because Sarah Wells… there’s an episode where Sarah’s talking about strategy, and one of the things that she says about good strategy is, you know it’s a good strategy if you can imagine yourself doing the other thing– doing it differently. It gives you choices, and those choices– I think the recording of those choices– is super important.

You said that all the different things that you’ve done, “Usually if you see my face, something terrible has happened.” There’s an incident, or things aren’t working the way they’re supposed to be doing. And the most common situation is I’ll say, “OK. Tell me what you’re doing, and why you’re doing it.” And they can tell us what they’re doing, but nobody can tell me why. They just can’t remember. It’s lost in the sands of time.

I mentioned to you also that Chris Swan had said his company, Atsign, publishes all their decision records in the GitHub repos that are public, for all the code. And you said you do something similar. Can you talk about that?

PB: Sure. The value of documentation is proportional to the access that people have to it.

NS: Yeah.

PB: Which usually means the proximity to the tools that they’re using. For engineers in particular, having your ADRs in, if you’re a monorepo in that repo, amazing. Because then it’s tracked directly with the repo.

If you’re scattered and you have a bunch of repos, that’s still fine, so long as it’s in a repo. That’s great. Because not only do you have the current state of things, but you also have the historical record of how the ADRs have changed over time. That’s huge.

NS: I just saw something that really excited me the other day, because I’m kind of a space junkie, and somebody put all the code for the Apollo capsule to get from the Earth to the moon and land. And what was so wonderful about it is that all the original comments are in there, so you can actually track the whole thing and see what they were thinking. And it’s really…. Yeah, it’s a wonderful artifact.

PB: It’s funny. There’s this idea of code archaeology. Of, “Hey, how did we get here from there?” That can be really delightful, but, if you’re working in a high-pressure environment, you don’t have time for that.

NS: Right, exactly. It might be delightful, but not on a Tuesday when you’ve gotta push something out to prod.

PB: Right? And that’s where this documentation falls down. You can have a lot of people who are enthusiastic about writing the documentation. Over time you accumulate quite a bit of it.

When you come to a decision point, or you’re joining a team and you want to understand how they got to where they’re at, you don’t want to read through 500 DRs. You don’t want to read all the incident reports. You don’t want to do all this stuff.

So that’s always been the challenge. How do you get all this information into somebody’s head when it matters the most?

NS: All right. So what do you do? The first takeaway here is: you will hit a point, probably early in your company’s life, maybe earlier than you might expect, where you’ve got to just start writing things down if you have any intent at all of success. Then for… people get sick, people move, people get better jobs, people get fired… you just have to make sure that these records exist.

Can you talk a little bit about some of the things that people should be thinking about doing as they’re making these DRs, and are there different sizes?

I’ll just give you an example. We’re working with a company on an information security program, and one of the things that we found was that the executives don’t have a culture of accepting risks on behalf of their department. It’s just the way the company grew up, right? The security team would decide “Is this allowed, or is this refused or forbidden?”

And I said, “That really isn’t the job of the security team. The security team’s job is to articulate risks in an understandable way, but it’s the executive’s job to take the decision about the risk.” And they liked that very much. And we started doing it, and it’s really made a difference quickly.

I think one of the most important things that we did was we, for everything that they’re considering, we make a threat model, we make a risk map, and then we present that to the executive in charge of whatever department is doing this. And as soon as they make that decision, that becomes part of that document, that threat model and risk map and the decision record about, “Here are the people who are present. Here’s the executive we briefed. Here’s what they said. Here’s what we’ve decided to do.”

Wow, is that valuable! Even a month or three months later, people do tend to forget the context.

Can you talk a little bit about some of the things that you either talk about with your clients or do yourself?

PB: Sure. It’s funny you use the word context, because it’s actually very closely related to how things have shifted a lot in the last two years since AI has come on the scene. I know that there’s a lot of hopes and dreams and also a lot of pessimism and cynicism around AI, but one of the things that it’s extraordinarily good at is digesting a lot of documentation and giving you kind of the nuggets that are useful to you. That is the most recent practice that I’ve been getting at with people is, “How do you make DRs, your threat assessments, your risk models… how do you make all of that available to an AI in context, so that you have the ability to inquire, or get that additional context, when you’re making other decisions?”"

NS: That’s interesting. Have you found any hallucinations? Have you found any inaccuracies?

PB: Oh sure. Totally. But that happens with people, too.

NS: Of course it does. But we typically don’t feed 70MB of notes from the last month into a person.

PB: Absolutely. There’s definitely an aspect… but even with people, when you’re talking about critical decisions, it’s always “trust but verify.” You want to trust someone did the work and did the thing, but if you’re a responsible executive, if you’re a responsible manager, you’re going through and you’re just double checking. “Does this smell right? Does this map to what my experience has been? Does this seem like the right thing?”

That’s part of your job. If you’re going to accept responsibility, you actually have to understand what you’re making decisions about.

NS: Yeah. Absolutely. Okay. That’s good.

However you’re gathering these things, using AI can help you, at the very least, organize and make it more digestible to the people down the road.

Are you doing this proactively? Are you just saying, “Here, let’s make this so that nobody’s reading the actual DRs. They can just read the AI nuggets.”? Or is it only ex-post-facto where it’s like, “Okay, we did this. I wonder what the hell we discussed? Here, suck all this stuff in and tell us what I meant.”?

PB: Yeah. It’s so context dependent. When I’m on an incident call, or something like that, it doesn’t have to be a critical thing. It might be just a 15-minute call where everyone’s on the line, and you make a decision about what happened. Usually you’ve appointed a note-taker who’s going to be recording all of the information that’s happened. Well, oftentimes you can just have a transcript of that done automatically on the call, and then you can try to digest it personally after the fact or use AI.

Everything’s moving so quickly. It’s changing so quickly that at the heart of this is the spirit of experimentation. You need human in the loop. You need to have this idea of a personal expert.

Nick, you’re an expert. I call you when I have security concerns. “How does this process work? Who do I need to call? What’s going on?” I don’t think I would trust an AI to that.

NS: I definitely would not. I mentioned Sarah earlier, and I’m going to mention her again just because I’m in the Sarah fan club, but one of the things that she said in a blog that she wrote for us yesterday was that a really important thing as an engineer when you’re considering tech debt is, you need to be able to explain to your manager, your manager’s managers, to execuitives, in plain English, what is the problem with what they’re asking you to do. Because a lot of times you end up in a situation where the leadership doesn’t quite understand that they’re both expecting innovation and not expecting to have to rewind and go back and fix things. You can’t do something you’ve never done before unless you’re prepared to do that. So as you say, the context is really super important.

PB: It’s the communication thing, right? Here’s the funny thing about the communication part, is that I’ve learned through like 25 years of failure and scar tissue how to do that translation effectively. When I’m talking with an engineer, or when I’m talking with an executive, even with that scar tissue and that experience that I have, I still now do rely on AI to give me feedback.

NS: All right. What are some of the things that we can do without AI, though? Because now we’re talking about DRs and ADRs and like…

PB: Oh, sorry.

NS: No, don’t be sorry. This is an actually important part of what everybody’s doing. So it made complete sense.

PB: If it’s a good document, just to touch on AI one more time, if it’s a good documentation process, it’s good for AI. If it’s a sound process– so we can talk about DRs, we can talk ADRs, incident reports… whatever it is– if you’re doing a good job there, it’s going to help you in the future, and just get better with AIs able to digest and give you that context.

The thing I really loved about Sarah’s take on tech debt and all of that was the decision-making processes. Understanding and recording what that is, right? It’s not just, “Your source code, and your artifacts, and your product represent the decisions that were made.” You understand that a decision was made, but it’s really important to understand why it was made, and how it was made and who made it. Who participated?

I want to be able to go back and say, “We’ve got this weird facade pattern going over here that protects the mainframe from blah, blah, blah, blah, blah. Who was involved in this? Because I’m curious about how it got written or what was going on or… where should I look? Because we have this security issue that we need to address, and I don’t know what’s going on.” Having that recorded in your DRs is the most important thing a DR can do. “What did you look at? Who was involved? What did we decide not to do, and why?”

NS: Right. But now you run up against the ceiling of the fact that engineers hate writing things down. I can’t tell you how many times I’ve looked in a repo and seen a commit… I see something, and the comment is, “Update.” And that’s all they had time to write in there.

Is it too much to consider, or is it too much to expect, that people would actually take the time? Obviously I’m thinking it suggests that on the first time you’re making a big decision, yeah, you’re going to write all this stuff down. But do you have a heuristic that you use to try to figure out when this is right or when this is wrong?

PB: The after-the-fact test I love is to bring someone new in and say, “Hey, do you understand what this is about?”

NS: Yeah.

PB: Because it is funny. You have the same people who respond to incidents together. You have the same people who make architectural decisions together. You have the same people who build your front end together. They get comfortable working with each other, so the documentation starts to fall off.

NS: Oh, yes.

PB: It’s not really “rot” in the sense that you built something and it’s going sideways. It’s that it never gets written, because you just have new people– er, you have the same people involved every time. I find it critical to involve new people when you’re going through this loop– hopefully people who can raise their hand and say, “Hey, I don’t understand. Explain it to me like I’m five.” That sort of thing.

NS: Absolutely.

All right. So, it sounds like we have the magic three. Which is: write things down because it makes things easier. Especially if you’re at a startup and you’re starting to hit that place where your future success is going to depend on remembering… and not just knowing… that being able to look it up, as opposed to just counting on people to remember.

The second thing is: AI can help. It might not be able to help with the decision record writing, but it certainly can help organize the decision records that you’ve made and put them into themes and put them into… be able to say, contextually, what people were thinking.

And the third one is: if you’re starting a program of DRs, ADRs… a really good idea, from the very beginning, is to bring in a completely uninvolved engineer and say, “Here, take a look at this and tell me if you can follow the thread– if you can follow the bouncing ball.” And get a sense from their feedback about what you need to change to improve the way you’re writing it down.

The goal is that some person off the street can come in and figure out not just what you made, but why you made it, what your intent was, and why you didn’t do it a different way. Do I have it?

PB: Yeah. I would say that’s not even the goal. That’s the reality.

NS: Yes.

PB: Because there is going to be some girl you hire off the street who’s going to come in and be like, “Why did this happen?”

NS: Yes. Or if we’re all lucky, you’ll get acquired. And then the acquiring company will have the same problem that they’re going to have to bring in a whole new team, etc..

All right. I mean, this is really interesting. I really appreciate the time. Thank you so much, Peat, for joining.

PB: Thank you Nick. It’s always a pleasure.

NS: Yeah, we really appreciate it. And this has been Velocity’s Edge. I’m Nick Selby.