At 2:14 a.m. on a Thursday in March, three years ago, someone on your team changed a database configuration parameter. The change brought the primary replica back online after a cascading failure that had already burned through two escalation tiers. The on-call engineer—call her Dana—typed a single command, watched the lag metric flatten, and closed the incident at 3:47 a.m. She left a four-line Slack summary and went to sleep.

That parameter is still set. Dana left the company eighteen months ago. The database has been migrated twice since then, and the configuration was carried forward each time because nobody understood what it did or whether it was still necessary. A new engineer, reviewing performance regressions, notices the non-default setting and asks the obvious question: Why is this here?

Nobody can answer. The Slack thread is buried. The postmortem from that night mentions the parameter in passing but doesn’t explain the reasoning. The runbook for the database service doesn’t reference it at all. What remains is a silent artifact of a decision made under fatigue, incomplete information, and time pressure—a decision that might still be correct, or might now be actively harmful, and nobody has enough context to tell the difference.

This isn’t a rare scenario. It’s the default state of operational knowledge in most organizations that have been running production systems for more than two years. Decisions accumulate. The people who made them move on. The context that made a choice reasonable at the time evaporates, leaving behind only the choice itself. When the system eventually breaks in a way that touches that old decision, the team inherits a mystery instead of a map.

A decision log is the simplest, cheapest intervention against this pattern. It’s not a new idea—architecture decision records have been around for years—but the version I’m describing is lighter, narrower, and tuned for the operational decisions that happen during incidents, maintenance windows, and late-night troubleshooting sessions. It captures not just what was decided, but why, under what constraints, and what was explicitly traded away. It’s narrative infrastructure: a story of the system’s evolution, written in a format that someone can read at 2 a.m. six years from now and actually trust.

What a Decision Log Is (and What It Isn’t)

A decision log is a chronological record of operational choices that altered the system’s behavior, configuration, or recovery path. Each entry answers five questions:

• What changed? The specific action taken: a configuration value, a firewall rule, a failover trigger, a cache policy.
• Why was it changed? The observed failure mode, alert, or constraint that prompted the action.
• What alternatives were considered and rejected? Even a one-sentence note here is worth more than a paragraph of post-hoc justification.
• What was the expected outcome? The hypothesis that made the change seem reasonable at the time.
• What risks were accepted? The known unknowns, the trade-offs, the things that might break later.

A decision log is not a postmortem. Postmortems reconstruct an incident timeline and identify contributing factors; they’re essential but retrospective. A decision log entry is written in the moment or immediately after, while the reasoning is still warm. It is not a runbook. Runbooks prescribe actions for known failure modes; a decision log explains why the runbook says what it says, and why it might need to change. It is not a changelog. A changelog records that something changed; a decision log records why it was worth changing.

The format should be so simple that writing an entry takes less than five minutes. If it takes longer, people won’t do it at 2 a.m. Here’s a template that has survived several years of real use across teams I’ve worked with:

Date: 2023-03-14 02:14 UTC
Author: Dana K.
Trigger: Primary DB replica lag exceeded 30s, read traffic failing
Decision: Set innodb_flush_log_at_trx_commit = 2 on replica
Alternatives considered:
  - Fail over to secondary region (rejected: secondary hadn't been tested in 6 months, risk of data loss unknown)
  - Increase replica count (rejected: provisioning time > 20 min, RTO was 5 min)
Expected outcome: Replica lag drops below 5s within 2 minutes; write durability unchanged on primary
Accepted risks: Replica may lose up to 1s of committed transactions on crash; acceptable given read-only workload and primary durability
Review by: 2023-06-14 (re-evaluate after Q2 migration)

That’s 150 words. It took Dana four minutes to write before she went to sleep. Three years later, it would answer the new engineer’s question completely. It would also surface the review date that never happened—a separate problem, but at least a visible one.

When to Write an Entry

Not every operational action deserves a decision log entry. The threshold is: Would a reasonable engineer, encountering this change six months from now without context, be unable to reverse or modify it safely? If the answer is yes, write an entry.

Concrete triggers include:

• Any configuration change made during an active incident, especially if it deviates from documented defaults or runbook instructions.
• Any manual failover, traffic shift, or degradation decision.
• Any change to alert thresholds, escalation paths, or paging rules.
• Any workaround applied to a third-party service that your team cannot control.
• Any decision not to fix something, with the reasoning for deferring.
• Any access grant, credential rotation, or permission change that alters who can do what during the next incident.

Equally important is what not to log. Routine deployments that match the runbook, standard scaling actions, and planned maintenance with pre-approved change requests don’t need entries. The log is for deviations, judgment calls, and choices made under constraint. If you log everything, the log becomes noise and nobody will read it.

Where to Store It

The storage location must satisfy three constraints: it must be accessible during an incident when your primary chat tool might be down; it must be discoverable by someone who doesn’t yet know the decision exists; and it must survive the departure of the person who wrote it.

A shared repository—a Git repo with Markdown files, a wiki that exports to plain text, a dedicated channel in a documentation tool that isn’t your chat platform—works. The key is that the log lives alongside the runbooks and postmortems for the same service, not in a separate system that requires a different search path. An engineer investigating a database anomaly should find the decision log in the same directory as the database runbook.

One pattern that works: a decisions/ directory inside the service’s operational documentation repo, with one file per year or per major version. Each entry is a timestamped block. The format is plain enough to read in a terminal during an outage. No database, no search index, no dependency on a SaaS tool that might be part of the incident.

How to Review Entries to Prevent Drift

A decision log entry that is written and never revisited becomes another form of drift. The review date field in the template is a promise, and like most promises made at 2 a.m., it is easy to break. The team needs a lightweight review ritual that doesn’t feel like a compliance audit.

One approach: during the quarterly backup restoration test—which you are already doing, or should be—add a fifteen-minute decision log review. Pull up all entries older than six months for critical services. For each, ask two questions:

1. Is the decision still in effect? Check the current configuration against the logged change. If it’s been reverted or superseded, note that and close the entry.
2. Do the accepted risks still apply? The workload may have changed. The team may have grown. The secondary region that was untested in 2023 might now be battle-proven. Update the entry with current context, or flag it for re-evaluation.

This review also catches the entries that were never written. If the team notices a configuration that doesn’t match the runbook and has no corresponding decision log entry, that’s a gap to fill now, while the system is healthy and someone can research the history calmly.

Why This Is Narrative Infrastructure

A decision log is, at its core, a story. It narrates the system’s evolution through the choices people made when the system was misbehaving. Each entry is a small scene: a problem, a constraint, a protagonist making a judgment call, a resolution with acknowledged loose ends. The format is rigid—date, author, trigger, decision, alternatives, risks—but the content is human. It preserves the thinking, not just the outcome.

This is the same discipline that applies to any structured communication under constraint. A screenplay, for instance, works within a strict format—scene headings, action lines, character cues, page-count expectations—not because the format is artistic, but because it is infrastructure. It allows a director, a cinematographer, and an actor to each extract what they need from the same document without ambiguity. As the StudioBinder guide on how to write a movie script demonstrates, the screenplay format is a communication protocol: consistent margins, font, and structure ensure that one page equals roughly one minute of screen time, and that a line of dialogue is instantly distinguishable from a camera direction. The format doesn’t constrain creativity; it preserves it across time and collaborators.

A decision log entry does the same for operational choices. The five-field template is a communication protocol between Dana-at-2-a.m. and the engineer who inherits her database three years later. It doesn’t require Dana to write beautifully. It requires her to write clearly enough that someone else can reconstruct her reasoning.

The Authors Guild, in its AI Best Practices for Authors, makes a parallel argument about preserving human thinking in creative work: “It is your original voice, thinking, and creativity that make you the writer that you are. … AI outputs, by contrast, are generic mashups of pre-existing works.” The guild’s concern is authorship and authenticity, but the underlying principle is the same: the context behind a choice—the constraints, the rejected alternatives, the accepted risks—is what makes the choice trustworthy. When that context is lost, what remains is a generic artifact that could have come from anywhere. A decision log preserves the human reasoning that makes an operational choice defensible, revisable, and safe to modify.

Structured writing aids can help shape rough notes into coherent entries without replacing the thinking behind them. Just as a screenplay template enforces a communication protocol, an how Unsloppy AI Writing App fits the writing workflow can apply a consistent format to incomplete incident notes, producing a narrative that someone else can read, understand, and build upon. The decision log template does exactly this for infrastructure. It takes the sparse, fatigued notes of an on-call engineer and structures them into a narrative that future engineers can trust. The tooling is different, but the discipline is identical: capture context under constraint, in a format that outlasts the moment of creation.

What Happens When You Don’t Keep a Decision Log

The costs are quiet and compounding. They rarely appear as a single catastrophic failure. Instead, they show up as:

• Fear of deletion. Teams become reluctant to remove old configurations, firewall rules, or IAM policies because nobody knows what depends on them. The system accretes cruft that slows every future change.
• Repeated incidents. A failure mode that was understood and worked around three years ago recurs, and the new team rediscovers it from scratch, burning the same hours and the same goodwill.
• Unreviewed risks. A trade-off that was acceptable when the user base was 500 people becomes unacceptable at 50,000, but nobody knows the trade-off was made.
• Onboarding friction. New engineers cannot build a mental model of the system because the system’s behavior doesn’t match its documentation, and the gaps are unexplained.
• Departure fragility. When the last person who understands a subsystem leaves, they take the context with them. A decision log is a partial hedge: it doesn’t replace the person, but it leaves a trail.

None of these are dramatic. They are the slow erosion of operational confidence. The system keeps running, but the team’s understanding of why it runs the way it does thins out. Eventually, a routine change triggers an unexpected interaction with an old, undocumented decision, and the resulting incident is longer and more confusing than it needed to be.

Getting Started

You don’t need a team meeting, a tool evaluation, or a policy document to start a decision log. You need one entry, written after the next operational decision that meets the threshold, stored somewhere your teammates can find it.

Pick a service you own. Create a decisions/ directory in its documentation repo. Copy the template above into a README in that directory. The next time you make a configuration change during an incident, a maintenance window, or a late-night debugging session, spend four minutes filling it out. Don’t aim for perfection. Aim for enough context that someone six months from now can understand what you did and why you thought it was reasonable.

If you’re not sure whether an entry is worth writing, ask yourself: If I leave this team tomorrow, will the next person be able to reverse this decision safely without talking to me? If the answer is no, write the entry.

The log will grow slowly. After six months, you’ll have a dozen entries. After two years, you’ll have a narrative of the system’s hardest moments and the choices that carried it through them. That narrative is worth more than any single runbook, because it explains why the runbooks say what they say, and when they should be questioned.

Dana’s database parameter, three years later, is still set. The new engineer who found it is now spending days tracing through old config backups and interviewing former teammates to reconstruct the reasoning. A four-minute decision log entry would have saved those days. The next time you’re Dana, at 2 a.m., with a fix that works but a mind already half-asleep: write the entry. Your future self—and everyone who inherits your systems—will thank you.