What follows is fiction, though it will feel familiar to people who ship software for a living. A small platform group of five people, the kind that supports a handful of internal services, adopted a habit during a rough quarter: every time they made a tooling or architecture call, they wrote it down in a short decision log, along with what they expected to happen. Six months later, that log changed how they argued, onboarded and recovered from mistakes.
The quarter that started it
The trigger was an argument about job scheduling. The team ran nightly batch work through a patchwork of cron entries on three servers. Someone proposed moving everything to a workflow orchestrator. Someone else wanted a lighter queue-based approach. After an hour of debate they picked the queue, drifted into other work, and forgot the details.
Three weeks later a new engineer asked why the orchestrator had not been chosen. Nobody could answer clearly. The tech lead remembered “something about cost.” The operations engineer remembered “something about retries.” The argument restarted from zero, and the hour was spent twice.
The rule they adopted
The platform lead proposed one rule: any change that touches how services are built, deployed or scheduled gets a five-line entry in a file called DECISIONS.md at the top of the repository. The entry has to include the options considered, the reasoning, and one prediction that can be checked within two months. They agreed to try it for a quarter.
The first entry was the scheduling one, reconstructed from memory and labelled as such. It read: “Chose a queue with a worker pool over a full orchestrator. Alternatives: orchestrator, keep cron. Reason: the jobs are independent, we have no complex dependencies, and the team has no spare capacity to operate another control plane. Expect: fewer silent failures and simpler on-call. Check by the end of next month: count of jobs that failed without an alert.”
What the log caught in month one
When the date arrived, the team counted. Silent failures had dropped, but a different problem had appeared: retries piled up when a downstream service went slow, producing bursts that surprised the database. The prediction was half right. In the old world that would have been remembered as “the queue was a mistake.” With the log, they could say precisely: the choice solved the problem it was chosen for, and created a new one worth addressing with rate limits.
The follow-up entry noted: “Add a concurrency cap to the worker pool. Alternative: switch to the orchestrator after all. Reason: the issue is bursts, not missing features. Expect the database load spikes to flatten. Check in two weeks.” It did. The team kept the queue.
Onboarding got easier
The next surprise was how the log helped new starters. Instead of a long architecture document that was out of date within a month, a newcomer could read the last twenty entries in an afternoon and understand not only what the platform looked like but how the team thought. They saw which constraints mattered (limited operations time), which trade-offs the team usually made (simple over powerful) and which calls had been revised.
Questions that once started debates became short messages: “See the entry from March; if circumstances have changed, write a new one.” That reframed disagreement. Instead of fighting over the past, the team wrote down what had changed and decided afresh.
The temptation to over-engineer the process
Around month three, a well-meaning teammate suggested a form with fourteen fields and an approval workflow. The team resisted. Their own history showed why: the journal worked because it was cheap. They kept the five lines and added only one optional field, “revisit if”, for the conditions under which the choice should be reopened. Anything more risked turning a helpful habit into paperwork.
Teams that already weigh heavier questions before building, as described in a write-up with prompts worth working through ahead of a custom application project, can treat the journal as the place where answers to those questions are filed. Likewise, when the group debated a rebuild, the log held their reasoning on a choice similar to the one discussed in weighing a cosmetic redesign against a ground-up application.
A small, honest failure
Not every entry paid off. One call, to standardise on a single logging format, was recorded with the expectation that debugging time would fall. At review, nobody could show that it had. The team noted that they had no baseline, so the prediction was unfalsifiable. The lesson went into the log itself: expectations must name something measurable before the change, not after. From then on entries said things like “median time to find the failing service in an incident” rather than “debugging should feel easier.”
The side research
During a design discussion about account sign-in, one engineer looked at how other websites handle a central login, including a two-wheeler rental marketplace site, MotoShareGo, which signs users in through a shared account service. The team did not copy anything. The journal entry simply recorded that the reference was consulted, which idea they borrowed in principle, and which they chose to skip, so the origin of the pattern stayed traceable.
How the on-call rota felt the difference
The people who noticed the change most were whoever carried the pager. During incidents, the first question used to be “who set this up and why?” with nobody to ask at three in the morning. Now the responder opened the log, found the entry for the relevant service, and read the original assumptions. Sometimes the answer was right there: “Timeouts are deliberately short; we preferred failing fast over hanging.” Other times the entry revealed that an assumption had quietly stopped being true, which pointed directly at the cause.
The operations engineer began adding a final line to incident write-ups: “Which decision-log entry does this touch?” Over a few weeks it produced a useful map, showing which earlier choices kept resurfacing in incidents and deserved a second look.
Six months later
By the end of the second quarter the log held roughly thirty entries. Reviewing them together revealed patterns nobody had spotted individually. The team was consistently optimistic about migration time, usually off by about half again. They tended to underweight operational cost when excited about a new tool. And their best calls shared a trait: each had a clearly named condition for reopening it.
So they changed their habits. Estimates for migrations got a built-in cushion. Any proposal to adopt a new tool had to state who would operate it. Reviews moved into the regular retrospective, ten minutes at the end, reading two older entries aloud.
What you can borrow
- Keep the log in the repository, next to the work it describes.
- Limit entries to five lines plus an optional “revisit if.”
- Write at least one prediction you could measure with a number or a count.
- Schedule the check when you write the entry.
- Review a couple of old entries in each retrospective.
- Reconstruct old decisions, but label them as reconstructions.
Our team is imaginary; the mechanics are genuine and inexpensive. Begin with the next tooling call your own team makes, write the entry before the meeting ends, and give it a check date. Next quarter you will be glad to have the evidence in front of you, rather than an argument about who remembers it best.

