Decision Logs

Day 20 — Kill the Demo, Keep a Decision Log

Stakeholders don't walk out of a sprint review because the product is late. They walk out because they have no way to tell a good tradeoff from a bad one — and the demo you just ran spent forty-five minutes training them not to bother trying.

The demo that looked perfect

I've sat through demos where every ticket was closed, every screen looked finished, the click-through didn't stutter once — and the stakeholder still hung up looking uneasy. Nothing was broken. The problem is that "it looks done" and "they understood why we built it this way" are not the same thing, and a demo can only ever hand you the first one. You can watch a feature run flawlessly end to end and still have no idea whether the team made good calls getting there.

Why demos train the wrong instinct

A demo rewards whatever happens to be visually finished in the last two weeks. That's the whole mechanism. It has no way to surface the decision you almost made differently, the risk you're quietly carrying, or the tradeoff you accepted on purpose and would make again. So stakeholders — who are sharp, pattern-matching people, not passive observers — learn the only signal the ritual actually gives them: polish. Give it a few sprints and they stop asking what you decided and why, and start asking why the button isn't aligned, or whether it can be blue instead.

• ▹Demos show finish, not reasoning, so feedback drifts toward whatever's visible — spacing, copy, color, where a button sits
• ▹A pixel nit is safe to raise in a room. An architectural doubt is not. Stakeholders reach for the thing they can actually judge by looking at it
• ▹The team starts optimizing the demo itself, polishing the part that gets looked at instead of the part that's actually risky
• ▹AI-assisted coding makes this worse, not better — an agent can make a UI look finished in an afternoon, so the gap between "looks done" and "is sound" widens instead of closing

The second-order cost: no framework for the hard conversation

Here's where it actually costs you something. Every team eventually hits the moment where the right call is "we need to change the architecture" or "the approach we shipped two sprints back doesn't scale, we're replacing it." That's a legitimate thing to say — sometimes the only responsible thing to say. But a stakeholder who's spent three months grading screenshares has no framework for evaluating that claim. All they've got is a comparison to last week's demo, which looked fine, so the architecture change reads as an excuse, or a reversal, never as a decision. You've spent months training them to judge the wrong variable, and now, under pressure, you need them to judge a different one entirely. I've watched this play out almost word-for-word on AI-first teams: the week you have to say "the single-agent pipeline falls over past ten concurrent tasks, we're moving to a supervised fleet" is exactly the week the only mental model your stakeholder has is "but the demo worked."

Replace it: the decision log

The fix isn't a better demo. It's a different artifact, full stop — a decision log: a dated, running list of the real decisions made that week, the tradeoff that was actually on the table, and what got rejected and why. This is not a status report wearing a nicer font. A status report tells you what happened. A decision log tells you what was chosen, and what it cost to choose it.

What a real entry looks like

2026-09-22 — Decision: Keep single-agent review pipeline, don't split into a 3-agent fleet (planner/coder/reviewer) yet.

Tradeoff considered: fleet would likely speed up large-PR review, but meaningfully increases LLM spend and adds a coordination layer we have no tracing/observability for.

Rejected: fleet architecture, this quarter.
Why: we'd be debugging agent handoffs blind — no trace tooling in place.

Owner: Cong. Revisit: 2026-11-01, after trace tooling ships.

Notice what's missing: no screenshots, no done/not-done checklist. A stakeholder reading this can disagree with the reasoning — that's the entire point of writing it this way. Nobody can disagree with a checkmark.

The mechanics

• ▹Who writes it — the eng lead or EM, not the whole team. It's a synthesis artifact, not a status aggregation
• ▹Time cost — fifteen to twenty minutes a week if you tracked decisions as they happened. An hour if you're reconstructing it from memory, which is itself a signal you're deciding too casually
• ▹Cadence — weekly, async, delivered before any live walkthrough, never as a follow-up to one
• ▹Format — three to five entries, max. More than that and you're logging tasks, not decisions
• ▹When a stakeholder still wants a live walkthrough — give it, but only after they've read the log. The demo becomes an illustration of a decision they already understand, not the first time they're hearing about it

"But don't they need to see the product?"

Yes — just not as the trust-building ritual. Demos still happen. They just get demoted to an optional appendix: good for a stakeholder who wants to feel the product in their hands, irrelevant to whether they trust your judgment. The decision log carries the trust. The demo carries the vibe. Mixing the two up is the original mistake.

The measurable shift

Trust doesn't compound because a stakeholder watched your latest build run smoothly. It compounds because they can trace the logic behind five decisions in a row and watch the reasoning hold up each time. That's a slower signal than applause at a demo, but it's the only one that survives the week you have to tell them something they don't want to hear. Tomorrow: how to actually read that trust signal before it breaks — because by the time a stakeholder tells you "I don't trust this team anymore," you've usually had three weeks of warning you didn't catch.

Extend your knowledge

• ▹Start your own log this week — write down the last three decisions your team made that had a real rejected alternative, and share it async before your next demo
• ▹If your team runs AI coding agents, log the agent-architecture calls explicitly — single-agent vs. fleet, model choice, retry/fallback strategy. These are exactly the tradeoffs a demo can't show
• ▹Read Will Larson's writing on engineering strategy docs (lethain.com) — the decision log is a lightweight, weekly cousin of the same idea: externalize the reasoning, not just the outcome
• ▹If your team already writes ADRs for technical decisions, this is the same discipline pointed outward, at stakeholders, instead of at the codebase