What problem does this system address?
Organizations record what they decide but not why they decide it, creating a persistent gap where the rationale behind critical decisions disappears when the decision-makers leave or forget.
I audited 3 teams that had experienced significant personnel turnover (30%+ in the preceding year). Each team reported spending an average of 3.2 hours per week investigating past decisions: “Why did we choose this database?” “Why is this service deployed separately?” “Why did we reject the vendor solution?” The answers existed in the memories of people who had departed. The decisions were visible in the code and architecture. The reasoning was gone. According to organizational memory research, decision rationale is among the most perishable forms of institutional knowledge.
How is the system structured?
The system uses a 5-field template (decision, context, options considered, rationale, and consequences accepted) captured within 24 hours of each significant decision.
Step 1: Define what constitutes a “significant decision”
Not every decision needs a log entry. I defined significance using 3 criteria: the decision is difficult to reverse (cost more than 2 person-weeks to undo), the decision affects more than one team, or the decision involves choosing between viable alternatives. This filter reduced the logging burden from “everything” to approximately 3-5 decisions per team per month, which was sustainable.
Step 2: The 5-field template
Decision: one sentence stating what was decided. Context: 2-3 sentences describing the situation at the time. Options considered: brief description of each alternative evaluated. Rationale: why this option was chosen over the alternatives. Consequences accepted: what tradeoffs or risks were knowingly accepted. The entire entry takes 10-15 minutes to write. The template deliberately mirrors architecture decision records but is simplified for non-architectural decisions (process changes, vendor selections, staffing decisions).
Step 3: Integration into existing workflow
Decision logs live in the same repository or wiki as the team’s other documents, tagged by date and category. A weekly automated reminder asks each team lead: “Were any significant decisions made this week?” This prompt catches decisions that might otherwise go unrecorded. The log is searchable and linked from relevant code comments and documentation, creating a web of context around the organization’s choices.
How do you validate it works?
Measure the reduction in “why did we do this” investigation time and the frequency of relitigated decisions.
After 6 months: 142 decisions logged across 3 teams. “Why did we do this” investigation time dropped from 3.2 hours to 0.7 hours per team per week (78% reduction). Six specific instances were identified where a team member proposed revisiting a decision, consulted the log, found the rationale still valid, and dropped the proposal. Each of those avoided relitigations saved an estimated 4-8 hours of meeting and discussion time. The total investment was approximately 45 minutes per team per week in logging time. The return was measured in hours of recovered investigation time and prevented circular discussions. Decision logs are the organizational equivalent of observability for distributed systems: they make the internal reasoning of the organization visible and queryable.