I spent four hours last Tuesday hunting a bug I wrote myself. The real crime wasn't the bug, it was the amnesia. I stared at a block of code, knew my fingers had typed it, and had absolutely no memory of the thinking that produced it.
The Gospel of 'Just Ship It'
There's a powerful and mostly correct instinct for a solo founder to just build. The pressure is to ship, to get something into the hands of users, to see if the idea has legs. In that mode, anything that isn't writing code or designing UI feels like a distraction. It feels like bureaucracy for a team of one.
This is the gospel of velocity. Your worth is measured in commits, in TestFlight builds, in the speed at which you can turn a thought into a functioning feature. And for the first version of an app, that's not wrong. You're sprinting through a fog, trying to find solid ground. Documentation is a luxury you can't afford.
We idolize this phase. The late nights fueled by nothing but an idea, hammering away in Xcode until something flickers to life on the Simulator. It’s the romantic part of the story. The problem is that a career isn’t one sprint. It’s a series of marathons, and the habits that get you through the first mile will cripple you by mile ten.
I shipped my first dozen apps with this mindset. Move fast, fix the problems later. The code was the source of truth. If I wanted to know why something was the way it was, I’d just read the code. It seemed so efficient.
Paying the Amnesia Tax
That efficiency is an illusion. It’s a loan you take out against your future sanity, and the interest payments are brutal. I call it the Amnesia Tax. It’s the time you spend reverse-engineering your own logic because you failed to record the context.
Last Tuesday's bug hunt was a classic example. The app was PostProof, a little utility for formatting text for social media. A user reported that pasting text from a specific source was mangling Unicode characters. I found the responsible function quickly enough. It was a bizarre-looking string transformation. It felt wrong, but I knew I wouldn't have written it without a reason.
So the archaeology began. I used `git blame` to find the commit. The message was a masterpiece of unhelpful brevity: "Fix paste issue." Thanks, past-me. I checked the date. It was from a frantic week of updates eighteen months ago. Was it a workaround for a bug in iOS 17.2? A fix for a specific device? A concession to some third-party library I'd since removed?
I had no idea. The original context was gone. The 'why' behind the code had evaporated. I spent half a day trying to safely unwind a decision that probably took five minutes to make. That is the Amnesia Tax. It's the friction that grinds development to a halt, not with a bang, but with a thousand confused pauses.
The Five-Minute Log
My most valuable file in any project today is `decisions.md`. It lives in the root of the repository, and it has saved me more time than any linter, framework, or productivity tool.
It’s not a detailed technical spec. It’s a simple, running log of non-obvious choices. The format is brutally spartan, because if it's complicated, I won't use it. Each entry has four parts.
**Problem:** A one-sentence summary. *Example: Pasting from App X corrupts certain emoji.*
**Options:** A bulleted list of paths I considered. *Example: 1) Use a third-party parser. 2) Write a custom regex filter. 3) Pre-process the string on the pasteboard.*
**Decision:** What I chose to do. *Example: Chose option 3.*
**Reason:** The most important part. The 'why'. *Example: The third-party parser is too heavy for this simple utility. Regex is brittle with Unicode. Pre-processing is a targeted fix that avoids library dependencies and works around a suspected WebKit bug on paste. Revisit after next major iOS update.*
That’s it. The whole entry takes maybe five minutes to write, usually right after I've made the choice. It forces a moment of clarity. I have to articulate the trade-offs I'm making. It's a conversation with my future self, giving him the context he'll need when something inevitably breaks.
This isn't about creating bureaucracy. It's about respecting the work. The real work isn't typing. It's deciding. This log separates the decision from its implementation, and preserves it.
Building software is just a long chain of decisions. The code is the temporary artifact of those choices. Keeping a record of the choices, not the artifacts, is the one habit that creates sustainable momentum.