What a decision log is, and what makes one survive

A decision log is a single place where the choices a team makes are recorded alongside the reasoning. Not what changed — that is a changelog. Not how the system works — that is documentation. A decision log answers a narrower and more expensive question: why is it like this?

Why the question is expensive

The cost shows up in specific, recognisable moments. A new engineer proposes an approach that was tried and abandoned eighteen months ago, and nobody left can say precisely why it failed. A migration stalls because no one can establish whether a constraint is still real or is cargo from a vendor you no longer use. The same architectural argument is had for the third time, from scratch, because the first two conclusions were never written down.

Each of these is days of work spent rediscovering something the team already knew. The knowledge was not lost — it was in a thread, and the thread is unfindable.

What separates a log that lasts

• Capture happens where the decision happens. If recording is a separate chore afterwards, it will be skipped exactly when things are busiest — which is when the most consequential decisions get made.
• Rejected options are kept. A log that records only what was chosen cannot answer "did you consider X?", which is the most common question asked of it.
• Entries can supersede each other. Decisions get reversed. A log that cannot express "this replaced that" turns into a set of contradictory claims with no way to tell which is current.
• Search works on meaning. Nobody remembers the title of the entry they need. They remember roughly what it was about.
• Assumptions are tracked, not just stated. The reasoning behind a decision rests on things that were true at the time. Some of them stop being true.

Wiki pages are not decision logs

The usual instinct is a Confluence space or a docs folder, and it usually fails for the same two reasons. Wiki pages describe current state, so when a decision is reversed the old reasoning is edited away — destroying exactly the history the log existed to keep. And a wiki requires someone to remember to update it, which is a promise about human attention that no team keeps under pressure.

Where Ecko fits

Ecko builds the log from the discussions your team is already having in GitHub and Slack. It extracts what was decided, the reasoning, and the alternatives that lost; links decisions that supersede or contradict each other; makes the whole thing searchable by meaning rather than keyword; and tracks the assumptions each decision depends on so you hear about it when one goes stale.