milestone

Record a milestone

A git log says what changed. It rarely says why the change was worth making, and never says which areas moved together. Six months later that is what somebody needs — usually while deciding whether they are allowed to undo it.

When to write one

For a change big enough that a newcomer would ask "why is this part like that?"

• a migration — a database, an auth model, a framework
• a rewrite of a module, or a service split in two
• a design reversal: something was done one way, then deliberately undone

Roughly a handful a year on an active repository. If you are writing one a week, they are commits, not milestones, and the file stops being readable.

When not to

• A task, or something in progress. That is STATE.md, or a session record.
• A single decision with no structural change. That is /chamnan:remember → .chamnan/memory/decisions/.
• A repeated procedure. That is /chamnan:capture.
• Anything with a status, an owner, or a due date. This is not project management, and adding those fields would quietly turn it into a worse version of a tool you already have.

Where it goes

.chamnan/milestones.md

One file, and entries are appended at the end. Newest last is deliberate: appending keeps every diff to added lines, where prepending would rewrite the context of the whole file each time.

The format

## 2026-08-20 — Authentication migration

**Why:** sessions dropped under load; the old design held state per node.
**Affected:** auth module, API layer
**Decisions:** short-lived tokens; the old endpoint stays for one release

Four parts, and the middle two carry the value:

Date and title	ISO date, then a short name for the change
Why	The problem that made it worth doing. Not "we migrated auth" — what was going wrong.
Affected	Which areas moved together. This is what nobody can reconstruct later.
Decisions	Choices made along the way, especially anything ruled out.