milestonelisted

# 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 ```markdown ## 2026-08-20 — Authentication migration **Why:** sessions dropped under load; the old d