Why we document every decision

Most projects fail not because of bad code but because of undocumented decisions.

When the context lives only in someone's head, the next engineer inherits the output without the reasoning. They reverse-engineer intent from implementation. They make assumptions that contradict the original constraints. Eventually they rewrite something that was correct — they just didn't know why.

What a decision record actually contains

The format matters less than the content. We write decision memos with three things:

**The context.** What was true at the time the decision was made. What constraints existed. What alternatives were considered. This is the part that rots fastest, which is why it's the most important to capture immediately.

**The decision.** What we chose and why. Not "we chose Postgres" but "we chose Postgres because our query patterns are relational, the team has depth there, and we need row-level security that most alternatives don't handle as cleanly."

**The consequences.** What we expect to be true after this decision. What gets easier. What gets harder. What would change the decision if it were different.

Why this compounds over time

A decision record is useless the day it's written. It becomes valuable six months later when someone asks why something is the way it is, and instead of shrugging, you can point to the memo that explains it.

The real value is architectural coherence over time. Systems that document their decisions stay coherent longer because new decisions can reference old ones. You're building a decision graph, not just a codebase.

The discipline

The only way this works is if it's done immediately, not retroactively. Retroactive documentation is archaeology — you're reconstructing intent from artifacts. Real documentation is journalism. Write it while you're still in the room.

We write a brief decision record for every architectural choice, every technology selection, and every time we say no to something a client asks for. The nos especially.