TDRs in the AI age: When the decision was made by a model

Three questions, one assumption

A TDR answers three questions:

• What did we choose?
• Why did we choose it?
• What did we consider and discard?

The structure is simple, and it has proven robust. I’ve written about it both in Standards that actually stick (in Norwegian) and in Handling disagreement in technology choices (in Norwegian).

In 2011, Michael Nygard described a simple format for Architecture Decision Records: title, context, decision, status, and consequences. His template has no separate section for alternatives considered. MADR does, making the options and trade-offs explicit. I write TDR because the decisions worth recording in a team are rarely only architectural.

But the structure rests on an assumption: that someone actually evaluated the alternatives. And what happens when the evaluation took place in a chat that’s now closed, with alternatives no one remembers, suggested by a model that doesn’t know the system?

Decisions without a trace

Imagine a developer choosing a caching strategy. Instead of a design review, they have a conversation with AI. Twenty minutes later the choice is made, the code generated, the PR opened. The developer records neither the assumptions nor the alternatives in the PR. The choice may be excellent, but the reasoning stays in the chat.

For the rest of the team, the decision is hard to follow:

• no one knows which alternatives were considered
• no one knows which premises the model was given
• no one can retrace the reasoning

Six months from now someone asks “why did we choose this?” The PR shows what changed, but no one can explain why. The choice is recorded. The reasoning is missing. That is knowledge debt, the same mechanism described in Technical debt as a team phenomenon (in Norwegian), just faster.

“The AI suggested it” is not a justification

A TDR that only says “we chose X because the AI recommended it” tells us where the suggestion came from. It doesn’t tell us why it fits here. Which requirements does it meet? Which drawbacks does the team accept?

The model won’t be accountable for the consequences or maintain the code. The team will.

That is not only an engineering principle. When Air Canada told a Canadian tribunal it could not be held liable for what its own chatbot had told a customer, the tribunal called the submission remarkable – the chatbot “is still just a part of Air Canada’s website” – and the airline was ordered to pay damages (Moffatt v. Air Canada, 2024 BCCRT 149). In this case, the organization was held responsible for the chatbot’s misinformation. That doesn’t settle liability in every AI case, but it shows that pointing to the model does not in itself remove the organization’s responsibility.

So the same rule as always applies: the justification in a TDR must be the team’s justification. AI may have illuminated the alternatives, challenged assumptions, exposed pitfalls, and that’s excellent. But what gets documented is what you weighed, and why.

The updated TDR

In practice the template barely needs to change. But two things deserve a place:

1. The process trace

You can start with one line:

“The alternatives were explored in dialogue with AI. The comparison below is our evaluation of the suggestions.”

That line tells readers where the suggestions came from, but not how thoroughly they were evaluated. Add what you actually examined: documentation, production experience, measurements, or a prototype. Separate what you’ve checked from what you’re still assuming. Then the next reader can see what the decision rests on.

2. The premises

The premises you give the model influence the suggestions you get. “What’s the best caching strategy?” and “what’s the best caching strategy for a system with these traffic patterns and this infrastructure?” can lead to different suggestions.

Document the premises the decision rested on. That’s what the future will need when the context changes, and that’s when TDRs are worth the most.

What might this look like?

Take the caching decision from the opening. A simplified, hypothetical TDR excerpt could look like this:

Choice and premise: We will try a local cache for product descriptions. The data may be up to five minutes old; price and stock information are fetched separately and fall outside this decision.

Rejected alternative: For now, we are ruling out a shared cache to avoid another service to operate. We accept that instances may show different versions within the five-minute limit.

Validation before production: Run a load test with the expected number of instances. Check memory use, database load, and that expired data is no longer served. Attach the results to the decision.

Revisit when: Review the choice if freshness requirements become stricter, or if tests show that the solution exceeds agreed limits for memory use or database load.

This isn’t a recommendation to use a local cache. It’s an example of what a colleague needs to understand the choice, challenge it, and see what still needs checking.

AI as TDR author? Yes – with a review

AI can help turn a design review discussion into a readable draft. That can make documentation easier to start, especially when the team has already worked through the decision out loud.

But a tidy draft can also hide gaps. Review it with the people who made the decision. Are the premises right? Were the alternatives actually discussed, or did the model add them? Has a planned test suddenly become a completed one? Correct that before the document becomes part of the project’s memory.

Speed without memory

A TDR should preserve the why. That need remains when AI helps with both the suggestions and the writing.

As a tech lead, you can make this a small part of the workflow: leave time to review the reasoning when the team makes a technical choice. Ask what you chose, why, and what you ruled out. Let the people who will live with the solution challenge the answer.

Six months from now, a new colleague should be able to understand why you chose this solution, and what changes would make a different choice better.