Future Me Was a Stranger Who Inherited My Mess

The person who has caused me the most trouble on this entire project is a stranger who keeps inheriting my work and has absolutely no idea why any of it is the way it is. That future self opens files I wrote, stares at decisions I made, and cannot reconstruct what I was thinking no matter how hard they try. The stranger, of course, is me — just a few months later.

I used to think of documentation as a chore for teams, something you do so other people can understand your work. It took me a long time to realize that the most important other person I was writing for was a future version of myself who would share none of my current context, and who would be quietly furious at how little I bothered to leave behind.

The illusion that you will remember

The root of the problem is a very convincing illusion. When you make a decision, the reasoning behind it is vivid and obvious and present. The whole web of considerations — what you were trying to achieve, what you had just ruled out, what constraint forced your hand — is right there in your mind, alive and complete. In that moment, it is genuinely impossible to imagine ever forgetting it. Of course you will remember why you did this. It is obvious.

So you do not write it down. Why would you? And this is exactly the trap, because context evaporates astonishingly, almost violently, fast. The rich web of reasoning that made a choice feel inevitable dissolves within weeks, and what it leaves behind is a bare choice, sitting there with no visible reason attached to it at all.

Returning as a stranger to my own work

So months later I would open my own code and encounter decisions I simply could not explain. Why is it done this particular way? Why this specific value and not another? Why this ordering, this odd exception, this awkward little detour? Some past version of me had known the answer with total clarity. The present version had inherited only the conclusion, with all the reasoning torn out.

It is a genuinely disorienting feeling — being a stranger in your own work, distrusting the choices of someone you cannot interrogate, who happens to be you. It is like being handed the final line of a long proof with every step that led to it erased. The answer is right there. You just have no way of knowing whether to trust it, or what would break if you changed it.

The “what” is visible; the “why” is gone

Here is the asymmetry I had completely underestimated. Code is excellent at recording what you did. It is, by its nature, a precise record of the actions taken. But it almost never records why you did them, and the why is both the harder thing to reconstruct and the more important thing to preserve.

The what, I can always recover, because it is sitting right there in front of me to be re-read. The why — the intention, the rejected alternatives, the specific reason this strange shape was necessary — is gone the instant it leaves my head, unless I made the deliberate effort to capture it. And without the why, the what is nearly useless for the one thing I actually need to do, which is decide whether and how to change it. A record of decisions with no record of reasons is a map with all the labels rubbed off.

Undocumented decisions become untouchable

The most insidious consequence is what happens to a choice whose reason has been forgotten. It becomes load-bearing in a way you cannot assess. You do not know why it is there, which means you do not know what depends on it, which means you become afraid to touch it. And so it ossifies — not because it is good, but because it is mysterious.

A system slowly fills up with these little frozen mysteries: decisions everyone, including their own author, is now too nervous to disturb. The cruel irony is that I built them myself, and my own forgetting turned them into things I had to treat with superstitious caution. You cannot safely change what you do not understand, and it turns out you can very easily fail to understand something you wrote with your own hands, simply because you did not write down why.

Documentation is a letter to a stranger

The reframe that finally made this click was to stop thinking of notes as being for me, in some vague timeless sense, and start thinking of them as a letter to a specific stranger: the future version of me who will land in this code with none of my present context, none of my fresh reasoning, and a head full of entirely different problems.

That stranger deserves better than what I was leaving them. When I write for them generously — explaining what I was thinking, why I chose this over that, what to watch out for — I am doing one of the kindest and most practical things available to me. And when I leave them nothing, I am setting an ambush for a person who is, in every way that matters, on my side. Writing things down stopped feeling like bureaucracy and started feeling like simple decency toward someone I will inevitably become.

Write the why, not the what

The discipline is not to document everything, to be clear. Lovingly narrating the obvious is its own kind of noise, and a comment that just restates what the code plainly does is worse than nothing, because it adds clutter and tends to drift out of date. Over-documentation buries the signal as surely as under-documentation starves it.

The thing worth capturing is precisely the part that will not survive on its own: the why. The reasoning. The alternative you considered and rejected, and why you rejected it. The non-obvious constraint that forced an ugly choice. The thing that will look like a mistake later to someone who has forgotten the context — especially when that someone is you. A single honest sentence of “why” is very often worth more than pages of “what,” because the what was never the part in danger of being lost.

The deeper lesson: your context is not durable

Underneath all of it is the mistake I most needed to correct: I had believed, without ever examining the belief, that my present understanding would simply persist. It does not. Everything that feels crystal clear in your head right now is being quietly deleted, a little every day, and the only form of understanding that actually endures is the form you externalize — get out of your head and into something that will outlast the memory.

So now I try to treat my current clarity as exactly what it is: a perishable resource, vivid today and gone by next quarter. While it exists, I try to write it down, not because I doubt my memory in the abstract, but because I have met the stranger who inherits my forgetting, and I owe them more than I used to give. They are, after all, going to be me.

— No signals, no returns, not investment advice.