Decision Debt: The 'Why' Nobody Wrote Down

The Rebuild Nobody Could Explain

Halden is a six-person B2B software company. In 2024 they shipped a CSV importer with one strange detail: uploads were chunked into batches of 200 rows with a two-second pause between them. Slow. Ugly. But it worked.

Nobody wrote down why.

Fourteen months later a new engineer cleaned it up. Batching out, one tidy request in. Three days after that the importer started failing for every customer uploading more than a few hundred rows. The enrichment API had a rate limit the original engineer discovered the hard way and solved in code, without ever writing a sentence about it. The cleanup cost eleven days and one awkward call with a customer who'd been told the fix was 'a quick improvement.'

Now count what it actually cost. Not the eleven days, the decision that existed only in one person's memory and then, briefly, in a pull request nobody read closely.

Decision debt is the compounding cost of choices your team made but never recorded. It isn't really a documentation problem; docs usually exist. It's a retrieval problem that starts as a capture problem. The 'why' was never written at the moment writing it was cheap.

Every team tracks code, tickets, and dates. Almost nobody tracks reasoning. And reasoning is the one asset that doesn't ship, doesn't compile, and doesn't survive a resignation.

What Decision Debt Actually Is

Decision debt is the interest you pay on choices made without a short written record: re-litigating settled questions, rebuilding working systems, onboarding people into folklore. Unlike technical debt, it never shows up in a diff.

Technical debt is at least honest. It has a file name, a ticket, and a comment that says 'TODO: fix this properly.' In Atlassian's 2026 developer experience research, 44% of developers named technical debt as a source of friction. That's a lot, but you can point at it.

Decision debt has no file. It's the Slack thread from March. The verbal pricing exception for one customer. The hiring bar change that nobody announced but everyone enforces.

It comes in three flavors, and they cost different amounts:

1. Unfindable. The decision exists somewhere. Nobody can locate it in under ten minutes. This is the flavor behind the 51% of developers who name finding information as their top friction source.
2. Unattributed. You know the rule but not who set it or whether they still work here. Rules outlive their authors and lose their justification along the way.
3. Expired. The decision was correct for its assumptions, and the assumptions changed with nothing scheduled to notice.

The third one is the expensive one, because it looks like competence. Everyone follows a policy that made sense in 2023. Nobody asks whether it still does, because asking sounds like a lack of alignment.

Stack Overflow's 2026 survey found that 79% of developers regularly discover important context after the fact. That number isn't about missing documentation. It's about context arriving late, after the rebuild, after the incident, after the customer call. Late context is expensive context.

Technical debt shows up in the code. Decision debt shows up in the calendar.

The Forty Percent Nobody Budgets For

When Atlassian surveyed 1,155 developers and 405 engineering leaders in 2026, unclear requirements and lack of direction ranked as a friction source for 40% of them. That's not a coding problem. That's a decision nobody communicated.

Here's the full ranking of what developers said slows them down:

• Finding information: 51%
• Meetings: 50%
• Context switching between tools: 45%
• Technical debt: 44%
• Unclear requirements or lack of direction: 40%
• Silos and poor collaboration: 31%

Read that list again. Four of the top six are archaeology problems. Finding information is archaeology. Meetings, very often, are group archaeology, everyone gathering to reconstruct something that was never written down. Context switching is walking to another tool to dig. Unclear direction is a decision that never got recorded. Only technical debt is code-shaped.

And the digging is not a minor tax. The same rough picture shows up in Stack Overflow's data: more than 63% of developers said incomplete information prevented them from getting the right context, and 75% said they spend at least five hours a week searching for answers. Five hours. Per developer. Per week. Roughly a working day lost to retrieval, in a population that reports shipping faster than ever.

Which raises an awkward question: if more than half your team's friction is information-shaped, why does every retrospective end with an action item about test coverage?

Because friction that doesn't have a dashboard doesn't get fixed. The AI numbers make this sharper, not softer. 87% of developers said AI helped them ship faster and 80% said they delivered more without longer hours. But only 28% reported noticeably less friction than before AI. And the share who said AI saved them ten or more hours a week collapsed from 68% in 2025 to 25% in 2026.

AI gave the hours back. Nothing in the workflow told anyone where to put them.

Three Ways Decisions Evaporate

Decisions vanish through three doors, chat, meetings, and people, and a fourth one just opened. Each door leaves the decision technically made and practically invisible.

The chat door. A decision made in a thread belongs to whoever last scrolled past it. Chat is built for recency, not permanence. Ninety days later the message is buried, the search doesn't surface it, and the decision has quietly become company lore that new hires are expected to absorb by osmosis.

The meeting door. Meetings are friction for 50% of developers, which is why so much energy goes into cancelling them. But a forty-minute meeting that ends without a written decision doesn't save anything, it schedules a second meeting. Async work only functions when the written version carries the decision, the owner, the deadline, and the default action if nobody objects. Fewer meetings plus worse writing is a lateral move, not progress.

The resignation door. Obvious, but overrated. Knowledge rarely leaves all at once. It leaves when someone changes teams, takes parental leave, or gets pulled onto another project for a quarter and comes back to find their reasoning has been 'cleaned up' by someone well-meaning.

The fourth door opened recently. 65% of developers now regularly spend time correcting AI-generated work, and 29% name reviewing AI output as friction. Every one of those corrections is a decision: this approach over that one, because of this constraint. Most go unrecorded. Faros AI's analysis of more than 10,000 developers across 1,255 teams found high-adoption teams merged 98% more pull requests, saw review times rise 91%, and produced pull requests 154% larger. That's not a code problem. That's reasoning being generated faster than anyone can write it down.

A decision made in chat belongs to whoever last scrolled past it.

What a Decision Record Needs (and What It Doesn't)

A decision record is a short, permanent note capturing what was decided, why, what had to stay true, and when to revisit it. Six fields. Two minutes. Findable in a search bar forever.

The format isn't new. Michael Nygard popularized architecture decision records back in 2011, and there's a whole open catalog of ADR tooling and templates if you want the long version. ADRs work well for infrastructure choices. The mistake is assuming they're only for architecture. Most decisions your team makes aren't architectural, pricing exceptions, vendor picks, 'we're not supporting Safari for this feature,' a change to the hiring bar. The six-field shape works for all of them. The ceremony around it doesn't.

Here's the version I'd actually use:

| Field | What goes in it |

|---|---|

| Decision | One sentence, present tense: 'We batch enrichment calls in groups of 200.' |

| Constraint | What forced the choice, a rate limit, a budget, a legal review |

| Assumptions | What has to stay true for this to keep being right |

| Owner | One name. Not a team, not a committee |

| Review date | When to check whether the assumptions held |

| Reversal cost | Cheap, expensive, or a one-way door |

Now the list of things it doesn't need: a wiki page with fourteen mandatory fields, a template so heavy that people type 'TBD' and move on, a meeting, a vote, or a slide. Decision records die from ceremony far more often than from laziness.

The only test that matters: could a new hire find this in a search and understand it in thirty seconds? If not, it's a memo. Memos don't get read twice.

A decision record is a search result, not an essay.

Capture Latency: Why the Good Ones Never Get Written

Capture latency is the gap between making a decision and recording it. Under thirty seconds and it happens almost every time. Over two minutes and it stops happening. Most decision logs die here, not from laziness, but from distance.

Watch it play out. The decision lands in a call. The person who made it is now four clicks, one login, and a folder decision away from the place where it's 'supposed' to live. By the time the call ends, the decision has been reworded three times in their head, and the version that would have been useful is gone.

Compare two paths. Path A: eight seconds, type the sentence into the same command bar where tasks get created, tag it, done. Path B: ninety seconds of deciding which doc, which folder, which heading, and whether this is even worth recording.

Path B loses. Not because people are careless, because at ninety seconds, the honest answer to 'is this worth recording?' is often 'I'll do it later,' and later never arrives.

This is where the research gets interesting. A 2026 summary of DevOps and teamwork research found that teams planning and tracking work in one place were 4.1 times more likely to meet deadlines and 2.4 times more likely to focus on the work that mattered most. The mechanism is simple once you say it out loud: when there's exactly one place, there is no decision about where things go. And no decision about where things go means no delay and no orphaned notes in a second system.

The keyboard matters more than it sounds like it should. A command bar beats a dashboard because typing decided: /enrich rate limit is 200/min, batch in 200s takes less time than deliberating about whether to bother. Speed changes behavior. Willpower doesn't scale, but friction reduction does.

If recording a decision takes longer than making a sandwich, it won't get recorded.

Put the Decision Next to the Tasks It Created

Decisions and tasks fail differently when separated. The decision becomes folklore; the task becomes work with no visible reason behind it. Keeping both in the same system, a real single source of truth, is what makes either of them retrievable six months later.

One decision usually spawns three tasks. Those three tasks point back to one constraint. If they live in different tools, the person doing task number two has no idea the constraint exists. That's exactly how Halden's importer got rebuilt: the constraint lived in code, the task lived in a tracker, and the reasoning lived in nobody's head.

The pattern that holds up:

• Every task links to the decision that created it.
• Every decision lists the tasks it spawned.
• Every decision with a review date generates a task on that date.
• Information and action stay separate but adjacent, a decision is context, a task is a commitment, and neither should be buried inside the other.

The review date is the piece nearly everyone skips. A decision without a review date is a decision you're trusting forever. Your 2023 choices are not all still correct, and the only reason you don't know which ones are stale is that nobody scheduled the question.

And a note on AI, since it's now part of every workflow: assistants are genuinely good at retrieval. Ask one 'why do we batch enrichment requests?' and it can find the answer in seconds, if the answer was written down. If it wasn't, you'll get a confident, fluent, wrong explanation, which is worse than silence because it sounds like research. A decision log is what turns retrieval into something you can trust.

An AI can retrieve a decision. It cannot retrieve one you never made explicit.

The Teams That Win Will Be Able to Replay Their Thinking

Markets churn faster than reasoning does. Stripe transaction data cited in Forbes Tech Council coverage showed SaaS equity prices recovering to roughly pre-'SaaSpocalypse' levels, with new SaaS platform businesses on Stripe up more than 180% year over year. Entire categories get repriced, rebuilt, and re-named. The thinking underneath your product persists much longer than the product cycle.

So here's the test I'd apply to any team before a funding round, a reorg, or a hire: pick a decision you made eighteen months ago. Can you find it? Can you find what you assumed? Can you tell whether the assumption held?

Most teams fail all three questions and mistake the failure for normal.

Three things worth doing this week, none of which require a new tool:

1. Write down three decisions you made in the last seven days. Sixty seconds each. No template, no approval.
2. Put them in the same place your tasks live, not in a folder called Docs that opens once a quarter.
3. Add a review date to exactly one of them. Pick the one with the most expensive reversal.

The next advantage in software isn't raw speed; 87% of developers already say AI made them faster. The advantage is being able to explain, six months later, why you did it that way, and knowing whether that's still true. Teams that can replay their thinking don't just avoid repeating mistakes. They build on them.