What is a decision log, with examples from a real project

A decision log is a running record of the calls a team makes. Each entry says what was decided, why, which options were turned down, who made the call, and when to check whether it worked. It lets a new teammate, or an agent, understand why the work looks the way it does without asking the person who decided.

What goes into a decision log entry?

A useful entry answers five questions: what was the question, what did we pick, why, what did we not pick, and when do we check the result. Anything less and the entry turns into a status update.

The idea is not new. In 2011 Michael Nygard proposed architecture decision records for software teams: a title, the context, the decision, its status, and its consequences. His point was that teams do not dislike documentation, only documentation with no value. A short record of why is the kind with value.

A product decision log needs two more fields than a software record:

• The outcome it serves. Which result is this call meant to move?
• A check date. When will you look at whether it worked?

Why keep a decision log at all?

You keep a decision log so the reasons survive after the meeting ends. Without one, the team remembers the choice and forgets the reason, and the old debate starts again the next time someone new joins.

This matters more now that agents do part of the work. An agent can read a repository and see what exists. It cannot see why the team chose one path over another unless someone wrote it down. Our post on coordinating decisions across humans and AI agents covers that gap in more depth.

What do real decision log entries look like?

Real entries are short, and they name the options that lost. Here are three from our own work on this website in October 2026, written in the format above.

Entry 1: Do we publish comparison pages against other tools?

• Picked: No. Product pages may name a tool only once, in one question, as where the job is often done today.
• Why: Our rule is to describe each product by its own job, never as a stand-in for another tool. A comparison page would push us toward that claim.
• Not picked: One honest comparison page for a single product. Comparison pages for every tool.
• Check: Whether the questions on our product pages draw search traffic without a comparison page.

Entry 2: Do the document kits get public pages?

• Picked: Yes. One public page per kit, generated from the same catalog the product uses.
• Why: People search for templates, and a page generated from one source cannot drift from the product.
• Not picked: Keep kits inside the app. One list page with no page per kit.
• Check: Whether each kit page shows its real contents rather than a shared paragraph.

Entry 3: Do we add a full-text file for answer engines?

• Picked: Yes, a generated file that joins our agent guide with the full text of our docs.
• Why: An agent that fetches one file should get every fact in one read.
• Not picked: Keep only the short agent guide.
• Check: Whether answer engines describe the product accurately when asked.

None of these entries says whether the call worked yet. That is normal. A decision log records the bet first and the result later.

How do you know whether a decision worked?

You know a decision worked by asking at a set time, against the outcome it was meant to move. The question is simple: did this work, yes, not yet, or no?

The hard part is remembering to ask. Most teams decide, move on, and never look back. The check date in the entry is what brings the question back.

How does Way by Ask The W keep a decision log?

Way by Ask The W keeps the decision log as part of the project. Each decision records the question, the pick, the reason, the options not chosen, the owner, and a status: proposed, committed, shipped, or abandoned. Every pick gets a next check date.

When the last move on an outcome is marked done, Way asks once whether it worked. If the answer is no, the decision comes back with the other options, so the team can choose again with what it learned.

Decisions can be written by hand, and coding agents connected to Ask The W can record one when a person asks them to. A person still makes every call. Way keeps the record of it.

For the full picture of how Way keeps decisions, see decision log. For how to tell which calls need more review, read Reversible vs irreversible decisions.