Practice
Write the decision down, including what it cost
A decision record that only lists the upside is marketing. The useful half is the part where you say what you gave up.
01Six months later, nobody remembers why
Someone opens a pull request to replace the thing you chose. They are not wrong on the merits they can see — they simply cannot see the constraint that made the alternative impossible, because that constraint lived in a meeting in March.
The failure is not that the decision was bad. It is that the reasoning evaporated, so every few months the team re-litigates it from scratch with less context than the first time.
02Five lines is enough
- What we chose.
- What we chose it over — name the specific alternative, not "other options".
- The constraint that decided it.
- What it costs us. This is the line everyone skips and the only one that matters later.
- What would make us revisit it.
That last line is the one that turns a decision record from an archive into a tool. "We will revisit this when job volume passes a thousand a minute" gives the next person a trigger instead of an argument.
03The cost line is the credibility line
An engineer describing a decision with no downsides is either not finished thinking or is selling something. Every real choice trades one property for another. Writing "this adds fifteen minutes of latency and will not scale past a few thousand jobs a minute" is not an admission of weakness — it is the sentence that tells a reader you understood the trade rather than stumbled into it.
It is also the most useful thing in a portfolio. Anyone can list technologies. The signal is whether you can name what each one cost you.