Decision Log

A Decision Log is a tool or working technique used to 👉 record the reasoning behind decisions, not just the outcomes.

In simple terms, it documents what decision was made, why it was made, and under what context.

It is widely used in high-level engineering teams (Google, Amazon, Netflix) because it helps reduce repeated decisions and prevents systems from becoming “haunted” in the future.

📌 Why Decision Logs Matter

1. People forget reasons faster than expected

   • After 3 months → only the outcome remains
   • But the reason for choosing this approach over others is forgotten

2. Reduces repeated decision-making

3. Reduces blame within the team

   • ❌ Who chose this broken solution?
   • ✅ Given the information we had at the time, this made sense.

How to Write a Decision Log

A simple structure with 6 sections

• Decision: What decision are we making?
• Context: Constraints at the time
  • What information we had
  • What we didn’t know yet
• Options: Realistic alternatives that were considered
• Chosen: What was selected
• Why: Honest reasoning behind the choice
• Revisit when: When this decision should be reviewed again

Example Usage

Decision: Authentication strategy

Context:

• API-based system
• Requires horizontal scalability
• Backend team of 2 people
• No Redis available

Options:

1. Session-based authentication + Redis
2. JWT

Chosen:

• JWT

Why:

• Minimal infrastructure
• Easy deployment
• Low latency

Trade-offs:

• Token revocation is difficult
• Expiration must be handled carefully

Revisit when:

• User count > 1M
• Security-related incidents occur