003-what-id-do-differently.md
Why every write-up ends with what I got wrong
A consultant with no recorded mistakes has either done nothing or told you nothing.
I put a “what I’d do differently” section at the end of every engagement write-up. It started as a discipline for me and turned into the thing clients quote back most often.
Writing that section makes me go back through decisions I would otherwise be happy to leave alone. Once something works, it is tempting to let the outcome justify the whole process. A working system can still have taken an unnecessarily difficult route to get there.
Be specific enough to be useful
“Communicate earlier” is an easy thing to write. It asks very little of the writer and gives the next person almost nothing to use. I want to name the decision that needed a conversation, who needed to be involved, and what information would have changed the work.
The same applies to technical regrets. Suppose a team builds an abstraction before it has a second use for it. Saying that the abstraction was premature is a start. Explaining which assumption it encoded, and how the next requirement challenged that assumption, gives another engineer a way to recognise the situation.
There is a distinction I care about here: a decision can be reasonable with the information available and still turn out badly. Looking back should help me identify what I could have learned sooner. Judging an earlier decision as if I already knew the outcome makes the write-up unfair and less useful.
Put the correction into the work
An admission needs somewhere to go. If the lesson is that we left operational ownership unclear, the handoff should name an owner. If an assumption was never checked, the next plan should include a way to check it before implementation depends on it.
Some mistakes will remain a judgement call. I can explain the tradeoff and still be unsure whether I would choose differently under the same pressure. I prefer to leave that uncertainty visible. A polished account in which every problem produces an obvious lesson would make me suspicious of my own editing.
The rule I hold myself to is to write claims I could defend in a code review. That includes claims about my own work. The reader should be able to ask what happened, see the reasoning, and disagree with it without needing access to a story I left out.