The Indie Hacker Decision Log: Why Every Build Choice Deserves a Record

Three months into building your SaaS, you realize the onboarding flow is confusing. Users keep dropping off at step two. You want to simplify it — but as you look at the code, you realize it’s more complicated than it looks.

Why did I build it this way?

You can’t remember. The code doesn’t tell you. There’s no comment. No note. Just a structure that made sense at the time, with no trace of the reasoning that led to it.

This is the decision debt problem.

What Is Decision Debt?

Decision debt is what accumulates when you make choices without recording them.

It’s not technical debt — it’s contextual debt. The code still works. But you’ve lost the reasoning that explains why it works the way it does. And when you come back to change it, you’re operating blind.

Decision debt makes everything slower:

• Revisiting choices you already resolved
• Second-guessing solutions that were deliberately chosen
• Re-litigating scope you intentionally cut
• Forgetting the constraint that made the “wrong-looking” approach the right one

The Forgotten Constraint Problem

Here’s a common pattern: you make a technical decision based on a constraint. Maybe you chose a simpler approach because you were targeting a 2-week timeline. Maybe you cut a feature because you had 40 hours to launch.

Those constraints don’t live in your code. They live in your head.

Later — months later, or in a new context — you look at the code and think: this seems wrong. You start rebuilding it. Three hours in, you remember why you didn’t do it that way the first time.

The constraint was real. The decision was correct. You just forgot the reasoning.

What a Decision Log Actually Looks Like

A good decision log isn’t complicated. For each key choice, you capture:

1. What you decided — as specific as possible
2. Why you decided it — the actual reasoning, not just “seemed better”
3. What you considered — alternatives you evaluated and rejected
4. The context — timeline, constraints, what you knew at the time

You don’t need to do this for every code choice. But for anything that touches architecture, scope, product direction, or tech stack — write it down.

Example:

Decision: Use Supabase for auth instead of building custom auth

Why: Don’t want to handle tokens, refresh logic, and security in a side project with no security budget

Considered: Auth.js, Clerk (too expensive for early stage), rolling custom

Context: This is a solo project with a 60-day runway to first paying user. Speed > control right now.

Simple. 30 seconds to write. Infinitely valuable when you come back to it.

The Compound Effect

The value of a decision log compounds over time.

At month one, it’s mildly useful. At month six, when you’re refactoring and wondering why things are the way they are, it’s invaluable. At month twelve, if you’re bringing on a co-founder or first hire, it becomes onboarding documentation.

And there’s a secondary benefit: the act of writing decisions down forces you to think them through more clearly. A decision you can’t articulate in two sentences might not be as solid as you thought.

How to Start

The barrier to starting a decision log is almost zero:

• Use a notes app, a Notion page, or a simple markdown file
• Add an entry when you make a significant choice
• Include context, not just conclusions

Or, if you want something built specifically for this pattern, Makerlog’s decision log is designed exactly for this — structured enough to be useful, lightweight enough to actually use.

Your future self will thank you. So will anyone who ever has to work with your code.