The Changelog
Every change that matters lands in one file, dated, newest first. You never delete an old state. You supersede it, and the new entry names what it replaced. When you ask “what changed last month, and why?” the answer is one file you can read top to bottom. This is the cheapest layer in the whole guide and the most skipped.
Why a changelog, when you already have git
git already saves every version of every file. So why write a changelog on top of it? Because git (the tool that tracks every version of your files) answers “what bytes changed in this file?” The changelog answers “what changed in the business, and why?” Those are different questions, and the second is the one you actually ask.
A git entry that says “edited strategy.md” tells you nothing about why you dropped a product line or moved your prices. The changelog entry does, in one line, with a pointer to the decision behind it. git is the machine record. The changelog is the human record, the one a person (or a Claude session six months from now) reads to reconstruct how things got the way they are.
The one rule: append, never overwrite
This chapter installs a single principle: append, don’t overwrite. You never destroy history. When something changes, you add a new entry. When a new decision replaces an old one, you say so out loud and name the old one. You do not quietly delete the old decision and pretend it was never made.
It sounds too simple to matter. It is the one discipline that separates a system you can trust for years from one that lies to you the moment two files disagree and nobody marked which one won.
The two files that hold your history
_changelog.md: the running record
One file, at the top of your Codex. Every change that matters lands here, newest at top, one line each: date, file, and why.
# Change Log
> Append-only. Newest at top: date, file, one-line reason.
> This is the "what changed and why" view.
## 2026-06-12 · pricing.md · moved shipping to flat rate, cheaper to run and easier to explain
## 2026-06-05 · products.md · dropped the wholesale line, too much support for the marginThe best version of this file is written for you, not by you. If the
/vault-apply command writes each line when you confirm a
change, the changelog can’t drift from reality. Every line matches a
change that actually happened. Write it by hand and it drifts within a
week.
The supersede pattern in decisions.md
decisions.md is your dated, append-only decision log
(you built it in Memory). The changelog adds one habit: when a new
decision replaces an old one, it names what it supersedes.
## 2026-06-05 · Dropped the wholesale line
Decision. Stop selling wholesale. Focus the store on direct retail.
Supersedes. The earlier call to add a wholesale tier as a growth channel.
Why. Wholesale orders ate more support time than the margin was worth.The supersede line is the whole trick. The old decision is still there, intact and readable. Anyone reading top to bottom knows it was replaced, and exactly why. No silent overwrites. No two-truths problem where two files disagree and nobody can tell which is current.
Where the rule applies
Append-only protects your evidence and your decisions. It does not freeze your working documents.
| File or folder | Rule |
|---|---|
_changelog.md |
Append-only. The record is worthless if it can be rewritten. |
decisions.md |
Append-only. Supersede old entries, never edit them. |
meetings/ |
Append-only. A transcript is evidence. Editing it destroys the record. |
| Wiki sources | Immutable once saved. Sources are evidence, not drafts. |
Everything else (wiki pages, strategy docs, SOPs) is meant to change. Let the derived layer evolve freely. Never let the historical layer lie.
Pitfalls (the “if this, then that” guide)
| Situation | What to do |
|---|---|
| A decision entry is now wrong and you want to edit it | Don’t. Add a new entry that supersedes it. The wrong-then-corrected trail is more useful than a clean file. It shows your thinking moved. |
| You start hand-writing changelog lines | Stop. Route the change through /vault-apply so the file
writes itself. A hand-kept changelog drifts within a week. |
| A decision feels too small to log | If it changes a prior position, it needs a supersede entry no matter how small. If it’s new and consequential, log it. If it’s neither, skip it. |
| You deleted an old doc instead of marking it superseded | Restore it, add a “Superseded” note pointing to the decision that replaced it, and leave it. Deletion breaks the trail. |
| The changelog is getting long | Good. Length is the record. If it’s hard to scan, add a month index at the top. Never prune entries. |
| Two files disagree and neither says it’s superseded | This is the exact rot the pattern prevents. Pick the winner, write
the decision, mark the loser superseded. Your weekly
/vault-lint should catch this. |
| You never actually read the changelog | Add a 60-second look-back to your weekly ritual (Learning · 01). A record nobody reads is just storage. |
A worked version: Maya’s
Maya runs an online store and a small service business, plus a
content channel. Her _changelog.md sits at the top of her
Codex, one line per change:
- “Dropped the wholesale line, too much support for the margin.”
- “Moved shipping to flat rate, easier to explain than per-item.”
- “Cut posting from three videos a week to two, quality was slipping.”
In decisions.md, the wholesale entry names the earlier
decision it replaced, so the growth-channel idea is still on the record,
marked as superseded, not erased.
The payoff shows up when Maya asks Claude, “what changed last month, and why?” The answer comes from one file, in plain sentences, in a few seconds. She never digs through old versions or tries to remember. And because Claude reads the same file, it never re-suggests the wholesale line she already killed.
You’ve got it when
The first four put the history spine in place. The last two are the habit that keeps it useful.
The skills that help here
The /vault-apply command writes each changelog and
decision entry when you confirm a change, and
/sync-progress keeps project changelogs current. Both are
in the starter kit, with the full list in ../03-habits/01-skills-and-commands.md.
You can run this whole convention by hand without them.
Next chapter
→ 03-evals-and-drift.md.
The last Learning chapter: the lints and checks that catch when the
system’s outputs start drifting from what’s true.