We Stopped Letting AI Make Decisions. We Started Letting It Capture Them.

Last week, I was on an architecture review with one of our client teams. Someone raised a question about a data storage pattern they were using for session state: the pattern had tradeoffs that were starting to show up as the system scaled. A reasonable thing to surface.

What followed was a conversation I’ve had a version of on nearly every project I’ve worked on.

Thanks for reading! Subscribe for free to receive new posts and support our work.

“Why are we doing it this way?” “I think that was an early decision.” “Do you know the reasoning?” “Not really.” “Who made the call?” “James, I think. He’s not on the project anymore.”

Full stop. The reasoning is gone. The constraints that made the decision sensible are gone. What’s left is code doing something that nobody fully understands why. And now a team that should be debugging a scaling problem is instead reverse-engineering a decision that was made eight months ago, in a conversation that nobody wrote down.

This is the cost that’s invisible in week one and obvious in month eight.

The thing that disappears when decisions go undocumented

Last month, Skip and I wrote a piece in Series 1 called “Field Notes: How We Stopped Re-Litigating Every Decision.” That article named the business cost: the energy spent reconverging on conclusions that had already been reached, the trust erosion when people felt like nothing ever stayed decided, the status calls that felt like they were moving backward.

The Decision Record is the mechanism we built to close that loop.

The CRAFT Constitution’s second law is: decisions must be explicit. Not “we talked about it and nodded.” Not “I think we agreed.” Written down, with the reasoning attached. The law exists because we’ve watched the same failure pattern repeat across client engagements: a decision gets made verbally, nobody documents the why, the person who held the context moves on or gets busy, and six months later a new team member asks a question that a two-paragraph write-up would have answered immediately.

The problem isn’t that teams make bad decisions. Most teams make reasonably good decisions given their constraints.

The problem is that the decision is a point in time, and the reasoning that made it sensible is perishable. The code stays. The context evaporates.

What the Decision Record is

The DR is a short, structured artifact. Five fields. You can fill it out in ten minutes when the decision is fresh, or reconstruct it from a meeting transcript in about the same time using Claude. The goal isn’t comprehensiveness. The goal is capturing the things that will matter when someone asks the question six months from now.

What was decided.One sentence. Not “we discussed authentication options.” “We chose JWT over session cookies for API authentication.” The decision itself, stated clearly. If you can’t state it clearly in one sentence, the decision may not actually be made.

Why.The reasoning that led to this conclusion. This is the hardest field to fill in and the most valuable one to have. “It felt right” is not an entry. “JWT avoids server-side session storage, which matters because we’re running stateless containers that need to scale horizontally” is an entry. The reasoning is what makes the decision interpretable later. Without it, you have a log of conclusions with no way to evaluate whether they still make sense.

What we considered and rejected.The alternatives that were on the table, and why each one didn’t win. This is the field most teams skip. It’s also the field that answers the most questions: the new team member who asks “why not X?”, the stakeholder who suggests a direction you already evaluated, the debugging session where an alternate approach looks tempting.

If you didn’t document the rejection, you’ll evaluate the same option again. Probably more than once.

What would cause us to revisit this.The specific conditions under which this decision becomes wrong. A constraint changes. A dependency disappears. A scale threshold gets crossed. Without this field, you have a log of conclusions. With it, you have a system that can tell you when it’s stale. This is the field teams find most uncomfortable to fill in, because it requires admitting that no decision is permanent. That discomfort is exactly the point.

Owner and date. One person who made or ratified the call. A date. That’s it.

How AI fits into this

The main objection I hear to documentation of any kind is time. Teams are moving fast. Writing things down feels like overhead. That objection is reasonable, and it’s the thing we designed around.

The Decision Record workflow doesn’t require blocking thirty minutes after a decision to write a DR from scratch. It requires someone to paste the relevant artifact into Claude. A Slack thread. A meeting transcript (Fireflies gives us this automatically for most calls). A quick voice memo. Three sentences of context jotted down while the reasoning is still fresh.

Here’s the prompt we use:

You are helping a software team document a technical or product decision using a Decision Record. A Decision Record captures: what was decided, why, what alternatives were considered and rejected, and what conditions would cause this decision to be revisited.

Based on the following notes, generate a first-draft Decision Record using these five fields:

1. What was decided (one sentence)

2. Why (the reasoning, not just the conclusion)

3. Alternatives considered and rejected (what was on the table and why it didn’t win)

4. Revisit conditions (what would make this decision wrong — be specific)

5. Owner and date

For any field you can’t fill in confidently from the notes, write “Needs resolution” and explain what’s missing. The “Revisit conditions” field almost always requires the human to fill in — flag it clearly.

[Paste Slack thread, meeting notes, transcript excerpt, or conversation summary here]

The person who made the decision reviews the draft, corrects the reasoning where it’s off, and fills in the revisit conditions. That’s the part Claude can’t infer from a meeting transcript: the specific conditions under which the decision becomes wrong. That part requires the person who was in the room.

Total time, once you have the source material: five minutes instead of thirty.

What we’re seeing three months in

I want to be careful about what I claim here. Three months is a short sample. What I can say is that certain patterns are consistent across the teams running Decision Records.

The “why not X” question has a place to go.On teams with DR logs, the question “why aren’t we doing X instead?” either gets answered by the DR or reveals that X was never formally considered. Both outcomes are useful. The first saves a conversation. The second surfaces a gap.

Debugging context improves in a specific way.The benefit isn’t that DRs tell you what’s wrong. It’s that they tell you what the code was designed to do and under what constraints. “This is working the way it was designed to work, but the constraint that made this design sensible has since changed” is a fundamentally different diagnostic starting point than “this is doing something and we don’t know why.”

Onboarding has a new artifact class.A new engineer who has access to the DR log for a system can answer a lot of “why is it built this way?” questions without waiting for a senior person to be available. The institutional knowledge is in the document rather than in a person’s head.

The open question I can’t answer yet: whether teams maintain the habit past the first month without explicit process support. The DR only works if it actually gets written. We’re still figuring out what the right enforcement mechanism looks like, and I’m not going to pretend we have a finished answer.

Next week, Skip and I dig into the Context Graph: the artifact that sits above everything else in CRAFT. Most teams prompt AI cold. We maintain a structured context layer per project and feed it to Claude before any serious work starts. The difference in output quality is not subtle.

If this resonated, subscribe. We’re writing about what’s actually changing in software delivery, no hype, no hand-waving, just what we’re seeing on real projects.

Take-Home: Decision Record Template + Claude Prompt

Decision Record Template

Project/Feature:[Name or short identifier]

Decision:[What was decided, in one sentence. Not “we discussed X.” The actual conclusion.]

Date:[Date]

Owner:[One person who made or ratified this call]

Why:

[The reasoning that led to this conclusion. The specific factors, constraints, or observations that made this the right call at this point in time. “It felt right” is not an entry.]

Alternatives considered and rejected:

[Alternative 1]: [Why it didn’t win]

[Alternative 2]: [Why it didn’t win]

[Add as needed]

Revisit conditions:

[The specific conditions under which this decision becomes wrong. A constraint that changes. A scale threshold. A dependency that disappears. A business assumption that shifts. Be specific. If you can’t name revisit conditions, you may not fully understand why you made this decision.]

Context:

[Anything relevant to understanding this decision that doesn’t fit elsewhere: the constraints you were under, the timeline pressure, the question this resolved, the state of the codebase at the time. Optional, but useful for high-stakes decisions.]

Claude Prompt: Decision Record from Existing Notes

You are helping a software team document a technical or product decision using a Decision Record. A Decision Record captures: what was decided, why, what alternatives were considered and rejected, and what conditions would cause this decision to be revisited.

Based on the following notes, generate a first-draft Decision Record using these five fields:

1. What was decided (one sentence)

2. Why (the reasoning that led to this conclusion, not just the conclusion itself)

3. Alternatives considered and rejected (what was on the table and why it didn’t win)

4. Revisit conditions (the specific conditions under which this decision would be wrong)

5. Owner and date

For any field you can’t fill in confidently from the notes, write “Needs resolution” and briefly explain what’s missing. The “Revisit conditions” field almost always requires the human to fill in directly — flag it clearly and leave it for review.

[Paste Slack thread, meeting notes, Fireflies transcript excerpt, or conversation summary here]