Write The Message For Whoever Investigates The Fault Next Year

The audience for a change message is not your colleague today. It is a stranger tracing a problem backwards.

The message attached to a change has one reader who matters, and they are not present when it is written. They are somebody, possibly you, arriving twelve or eighteen months later with a symptom and a question: why is this line the way it is? They will trace the history back to your change and read whatever you left. If it restates the change itself, they learn nothing they could not see. If it records what was wrong before, why this approach was chosen, and what was considered and rejected, they have their answer in a minute rather than an afternoon of reconstruction.

This reframes the message from bureaucratic overhead to the cheapest durable documentation available. It sits permanently beside the exact lines it explains, and unlike a document elsewhere it cannot drift away from them. The useful content is the part that is about to be forgotten: the observed behaviour that prompted the work, the constraint that ruled out the simpler option, the deliberate decision to leave something unfixed for now and the reason. Two or three plain sentences will usually do it. The failure is almost never length, it is that the reasoning was never written at all.

There is a habit that makes this easy. Before you finish a piece of work, ask what you knew at the start that you no longer have to think about, because it has become obvious to you through familiarity. That knowledge is the thing the next reader lacks, and it is precisely what familiarity makes you forget to mention. Writing it down takes a minute and returns that minute many times over, usually to somebody who will never know they were spared the trouble. That is the ordinary shape of craft: invisible when it works.