I've journaled for years. The writing was never the problem. The problem was that entries piled up, scattered, and quietly contradicted each other — I'd settle something in January, un-settle it by March, and forget I'd ever decided. So I did the only thing that made sense to an engineer: I refactored it.
A journal is a log, not a database
Here is the thing I took embarrassingly long to notice. A journal is append-only storage with no read path. You write to it constantly and query it approximately never.
In any other system we'd call that a logging pipeline with no aggregation layer. Useful for forensics, if you happen to know the timestamp you're looking for. Useless for answering a question like "what do I actually believe about this?"
And because there's no read path, contradictions never surface. Two incompatible conclusions can sit in the same notebook for years and never once appear on the same screen. You don't notice you're flip-flopping. You just feel vaguely unsettled about the same topic, over and over, and each time you reason your way to an answer from scratch — as if the last three times never happened.
That re-derivation cost is the real tax. Not the writing. The forgetting.
The system, as it stands
This evolved over a couple of years rather than arriving fully formed. Four pieces.
1. Every entry is a file, version-controlled
Plain markdown, one file per entry, in a git repository. The date is in the filename. The commit history is the point: I can watch a belief change and see exactly when and why.
That sounds like overkill until the first time you run a diff on something you wrote two years ago and realise you've quietly reversed a position you'd have sworn you'd held consistently. Memory rewrites the past to feel coherent. Git doesn't.
2. Entries live in topic folders
Work, health, money, relationships, craft — the handful of areas that actually generate recurring decisions. Nothing clever. The folders exist so that when I want everything I've ever concluded about one area, it's one directory, not a chronological scavenger hunt.
3. One condensed principles doc sits on top
This is the piece that made the whole thing work. A single document of distilled rules, each one citing the entry it came from.
## Energy, not hours, is the binding constraint
Source: 2024-03-11-after-the-q1-crunch.md
Revised: 2025-08-02-resolution-side-projects.md
I keep optimising the calendar and then wondering why a free
afternoon produces nothing. Protect the state, not the slot.The citation is not decoration. A principle with no source is a vibe, and vibes are exactly what this system exists to replace. If I can't point at the day I learned something, I probably didn't learn it — I read it somewhere and liked how it sounded.
In database terms it's a materialised view: derived data, cheap to read, rebuilt from the source when the source changes. In practice it means the thing I consult is three pages, not three hundred.
4. Contradictions get a dated resolution doc
When I catch myself arguing against something I already settled, I don't just overwrite the old position. I write a resolution: what I used to think, what I think now, what changed, and what evidence moved me.
# Resolution — side projects, 2025-08-02
Held (2023-06): Ship side projects fast, momentum beats polish.
Held (2025-04): Never start anything I can't finish properly.
These are both defensible and I've been oscillating for 18 months.
Settled: the distinction isn't speed vs. polish, it's whether the
project has an external commitment attached. No commitment, ship
rough. Commitment, finish properly. The oscillation was me applying
one rule to two different categories.This is the closest thing to a merge commit. You don't silently take one side and pretend the conflict never existed — you record that there was a conflict, and how it was resolved. Six months later, when the same tension resurfaces, the work is already done.
What actually changed
My self-knowledge stopped living only in my head, where it contradicted itself silently. It became something I can query.
The concrete effect is narrower than it sounds, and more useful. I stopped re-litigating decisions I'd already made. Not all decisions — the ones worth revisiting still get revisited. But the ones I'd settled and then forgotten I'd settled now cost me nothing. That turns out to be a surprising amount of recovered attention.
The second effect I didn't expect: writing an entry got easier once I knew it had somewhere to go. An entry that feeds a principles doc has a job. A journal entry that disappears into an undifferentiated pile does not, and some part of me always knew that and wrote accordingly.
What I got wrong first
Three things, in case they save you the detour.
- I structured too early. I built the folder taxonomy before I had enough entries to know what the categories actually were. Half of them were empty a year later and two of the real themes had no home. Write first, let the structure emerge from volume.
- I wrote principles prematurely. An insight that has survived one good week is not a principle. It's a mood. I now wait until something has recurred — ideally until I've written about it from two different directions — before it earns a line in the distilled doc.
- I tried to make it comprehensive. The principles doc is valuable precisely because it's short enough to reread. Every time I've let it sprawl, I've stopped consulting it, and the whole system quietly reverted to being a log again.
You don't need git
The version control is genuinely useful to me, and it's also the least important part. I reach for git because it's already in my hands — the same reason a carpenter's shelves are suspiciously well-joined. If your tools are a notes app and a folder of documents, the system works the same.
What you actually need is smaller than the tooling suggests:
- One place where your conclusions are written down, separate from where your thinking is written down.
- Every conclusion traceable to the moment you reached it.
- A habit of revisiting — and an explicit way to record it when you change your mind, rather than silently overwriting.
That's the whole thing. Dated entries, a short distilled layer on top, citations between them, and honesty when the two disagree.
The part that generalises
Most of us keep re-deriving the same lessons because we never kept the last derivation. We treat our own conclusions as though they're cached in memory, when memory is the one component in the stack with no durability guarantees and a documented habit of rewriting history.
Treating my own thinking like a codebase to refactor has been one of the highest-leverage habits I've built — not because the metaphor is clever, but because refactoring has a specific meaning. You don't add features. You don't rewrite from scratch. You take something that already works, and you make its structure match what you've learned about it since.
Which is a reasonable description of what growing up is supposed to be, and a much better one than most.
Running something similar, or something better? I'd genuinely like to hear how it's structured — get in touch.
