Decision Journals

You cannot improve your decisions if you do not track them. Most engineering teams make hundreds of decisions per quarter — architecture choices, prioritization calls, hiring decisions, technology bets — and record almost none of them. When a decision turns out well, nobody knows why. When it turns out badly, nobody remembers the reasoning. The result is that decision-making quality never improves because there is no feedback loop.

The Problem with Invisible Decisions

Engineering post-mortems focus on incidents: something broke, here is what happened, here is what we will do differently. But most consequential decisions never trigger a post-mortem because their effects are slow and diffuse.

Decision: "Let's use MongoDB for this project."
Made: January 2024
Consequence: By August 2024, the team discovers they need
             transactions and relational queries that MongoDB
             handles poorly.
Post-mortem: None. The team just migrates to Postgres over
             3 months and moves on.
Learning captured: Zero.

Nobody records why MongoDB was chosen, what alternatives were considered, or what assumptions were made about the data model. When the next project starts and someone says "let's use MongoDB," the team has no institutional memory of the previous failure. The same mistake can repeat indefinitely.

What a Decision Journal Is

A decision journal is a structured record of decisions made, the context at the time, the reasoning behind them, and the expected outcomes. It is not a diary. It is an engineering artifact — as concrete as a design document or a test suite, and potentially more valuable than either.

Decision journal entry:

Date:        2026-02-15
Decision:    Use SQS instead of Kafka for the event pipeline.
Context:     Team of 4 engineers. 5,000 events/day currently.
             Expected to grow to 50,000/day in 12 months.
             No dedicated ops engineer.
Alternatives:
  - Kafka: More powerful, but requires dedicated ops. Cluster
    management is complex. Overkill for our volume.
  - Redis Streams: Familiar to the team, but no dead letter
    queue support and less durable than SQS.
  - SQS: Managed service, zero ops overhead, dead letter queue
    built in, handles our scale easily.
Reasoning:   At our current volume and team size, operational
             simplicity beats raw capability. SQS handles 10x
             our projected volume. If we outgrow it, migration
             to Kafka is feasible (the event format is service-
             independent).
Expected outcome: SQS works fine for 12+ months. We never think
                  about queue operations.
Risks:       If event volume exceeds 500k/day, SQS costs may
             become significant. If we need exactly-once
             processing, SQS is harder than Kafka.
Review date: 2026-08-15

This entry takes 15 minutes to write. It captures the decision, the reasoning, and the predictions in a format that is reviewable later.

Why Record Expected Outcomes

The most critical part of a decision journal is the expected outcome. Without it, you cannot learn from decisions because you cannot compare what you expected to happen with what actually happened.

Without expected outcome:
  Decision: Use SQS.
  6 months later: SQS is working fine.
  Learning: None. "It worked" tells you nothing about whether
  your reasoning was sound.

With expected outcome:
  Decision: Use SQS.
  Expected: Works for 12+ months, zero ops overhead.
  6 months later: SQS works but we're hitting throughput limits
  at 30k events/day — earlier than expected.
  Learning: Our growth projection was too conservative.
  We should pad estimates by 2x for event volume.

The expected outcome creates a testable prediction. When reality diverges from the prediction, you learn something specific about your reasoning. Over time, you calibrate: you discover which types of predictions you consistently get right and which you consistently get wrong.

Decision Journal vs ADR

Architecture Decision Records (ADRs) are a related practice in engineering. They record architectural decisions with context and reasoning. A decision journal is broader — it covers any significant decision, not just architectural ones — but the two are complementary.

ADR scope:
  Architectural and technical design decisions.
  "We will use PostgreSQL for the primary data store."
  "We will communicate between services via gRPC."

Decision journal scope:
  Any decision worth recording, including non-technical ones.
  "We will hire for senior roles first and backfill juniors later."
  "We will delay the launch by 2 weeks to fix the auth bug."
  "We will skip the rewrite and patch the existing system."
  Plus all the decisions that ADRs would cover.

If your team already writes ADRs, a decision journal extends the practice to decisions that ADRs do not cover. If your team does not write ADRs, a decision journal is a simpler starting point.

The Review Process

Writing the journal entry is half the value. The other half is reviewing entries after enough time has passed for outcomes to be visible. A quarterly review is the right cadence for most decisions.

Quarterly review process:

1. Pull up all entries from 3-6 months ago.
2. For each entry, answer:
   - What actually happened?
   - Did the outcome match the expectation?
   - If not, why? Was the reasoning flawed, or did the
     context change in an unpredictable way?
   - What would I do differently with the same information
     I had then (not information I have now)?
3. Record the review notes alongside the original entry.
4. Identify patterns across multiple entries.

The question in step 4 is the most valuable: "What patterns do I see across multiple decisions?" Common patterns include:

Pattern                          What it reveals
---                              ---
"I consistently underestimate    My growth projections are too
 how fast data volume grows."     conservative. Pad by 3x.

"I keep choosing the familiar    I may be satisficing too early on
 option without evaluating        decisions that deserve more analysis.
 alternatives."

"My decisions that involved      I should consult more people on
 consulting 3+ people turned      important decisions. My solo
 out better than solo ones."      reasoning has blind spots.

"I overweight technical          I need to factor in team skills
 elegance over team                and operational simplicity more.
 familiarity."

These patterns are invisible without a journal. You cannot learn from decisions you do not record.

Applying Decision Journals to Post-Mortems

Post-mortems are retrospective: something went wrong, and you analyze it after the fact. Decision journals are prospective: you record your reasoning before the outcome is known. Combining both creates a complete feedback loop.

Decision journal (before):
  "We decided to skip load testing because the deadline is tight.
   Expected outcome: the feature handles our normal traffic fine.
   Risk: if there's a traffic spike, we might see degraded
   performance."

Post-mortem (after):
  "The feature caused a 2-hour outage during a traffic spike.
   Root cause: no load testing was performed."

Combined learning:
  "We correctly identified the risk but chose to accept it
   under deadline pressure. The question is not 'should we have
   load tested?' (obviously yes in hindsight). The question is:
   'Under what conditions should we skip load testing, and
   under what conditions should we delay the launch instead?'
   
   New rule: Load testing can be skipped for features behind
   a feature flag with a 1% rollout. It cannot be skipped for
   features with full rollout."

The decision journal transforms the post-mortem from "we should have load tested" (obvious and not actionable) into a specific, nuanced guideline about when to accept risk and when not to.

Applying Decision Journals to Career Decisions

Career decisions are among the most consequential decisions engineers make, and among the least tracked. A decision journal applies the same rigor to career choices that engineers apply to technical ones.

Career decision journal entry:

Date:        2026-01-10
Decision:    Stay at current company instead of taking the offer
             from Company X.
Context:     Company X offers 30% more compensation. My current
             team is working on a challenging project that I'm
             excited about. Company X's project is less clear.
Reasoning:   The learning opportunity at my current company is
             higher for the next 12 months. The compensation
             difference is meaningful but not life-changing.
             I value the relationships I've built here.
Expected outcome: I'll learn a lot this year and be in a stronger
                  position for my next move.
Review date: 2027-01-10

Review (12 months later):
  The project was challenging and I learned a lot. Promoted to
  senior. Company X had layoffs 6 months later. Decision was
  sound for the right reasons.

Without the journal, this decision dissolves into memory. With the journal, it becomes a data point that calibrates future career reasoning.

Practical Implementation

A decision journal does not need to be elaborate. The key is consistency. Here is a minimal viable format:

Template:

Date:
Decision:
Context (2-3 sentences):
Alternatives considered:
Reasoning (why this option):
Expected outcome:
Risks:
Review date:

Store it wherever the team will actually use it. A shared document, a wiki page, a dedicated Slack channel, or a section of the project's repository. The format matters less than the habit.

Lightweight implementation:
  Create a DECISIONS.md file in the repo.
  Add an entry for every significant technical decision.
  Review entries during quarterly retrospectives.

Heavier implementation:
  Use a dedicated tool (Notion, Confluence, custom app).
  Add structured fields for filtering and analysis.
  Generate reports on prediction accuracy.

Start with the lightweight version. Migrate to the heavier version only if the team finds value and wants more structure.

What Counts as a "Significant" Decision

Not every decision needs a journal entry. Use this heuristic: if the decision affects more than one sprint or more than one team, record it.

Record:
  - Architecture choices
  - Technology selections
  - Major prioritization calls (what to build, what to defer)
  - Hiring decisions
  - Process changes
  - Decisions to accept or mitigate risk

Do not record:
  - Variable naming
  - Individual PR decisions (unless they set a precedent)
  - Daily standup outcomes
  - Lunch choices

Common Pitfalls

Writing entries but never reviewing them — the journal is worthless without the quarterly review. The review is where learning happens. Without it, you have a write-only log.
Recording the decision but not the reasoning — "We chose Postgres" is not useful. "We chose Postgres because our team knows it, our query patterns are relational, and we want ACID guarantees for financial data" is useful. The reasoning is the most valuable part.
Hindsight bias in reviews — when reviewing, you know the outcome. It is tempting to say "I should have known." The correct question is "with the information I had at the time, was the reasoning sound?" Sometimes good reasoning leads to bad outcomes. That is not a decision failure — it is variance.
Making the journal a bureaucratic burden — if entries take 30 minutes to write and require a committee review, nobody will do it. Keep it to 10-15 minutes per entry. Lightweight and consistent beats thorough and abandoned.
Only recording technical decisions — some of the most consequential decisions are about people, priorities, and process. A decision journal that only covers architecture misses the decisions that often matter more.
Not recording what you expect — an entry without an expected outcome is a history log, not a learning tool. The expected outcome is what makes the journal useful for calibrating your judgment.

Key Takeaways

You cannot improve decisions you do not track. A decision journal creates the feedback loop that makes better decisions possible.
Record the decision, the context, the alternatives, the reasoning, the expected outcome, and the risks. The expected outcome is the most critical field — it turns the entry into a testable prediction.
Review quarterly. Compare expected outcomes to actual outcomes. Look for patterns across multiple decisions. The patterns reveal your systematic biases.
Decision journals complement ADRs and post-mortems. ADRs cover architecture. Post-mortems cover incidents. Decision journals cover everything else.
Keep it lightweight. A decision journal that takes 10 minutes per entry and is used consistently is worth more than an elaborate system that is abandoned after a month.
Apply the practice to career decisions, not just technical ones. Career choices are high-stakes, long-horizon decisions that benefit enormously from structured recording and review.