| name | changelog |
| description | Record shipped work in the monthly changelog (append-only). Use when something ships or when asked "what changed", "add to changelog", "release notes", or "what shipped this month". |
changelog
The memory of the knowledge base. Every month gets one file; history is append-only. This is what the SessionStart hook surfaces so the agent starts each session knowing recent work. Pairs with author and router.
Golden rule: never delete or rewrite shipped history. Reversals get a new entry, not an edit.
Writing style (enforce)
Direct, tech + business. No filler. Outcome first.
- Each entry = a small table (Outcome / Delivered / Business impact / Commits). No narrative paragraphs.
- Summary = 4 bullets max: release type, biggest business change, biggest technical change, prod risk/action.
- Concrete only: feature names, paths, hashes, numbers. Cut adjectives.
1 — One file per month
changelog/(mmm-yy).md — lowercase 3-letter month + 2-digit year: (apr-26).md, (may-26).md.
changelog/README.md is the index: a table of | Month | Highlights |, newest first.
Link to a month file (parens need angle brackets): [may-26](<(may-26).md>).
2 — Anatomy of a month file
# Month YEAR — <release / period title>
> Window: `<base>` (`hash`, date) → `<head>` (`hash`, date). Scope: `N` commits.
## Summary
- Release type: patch | feature | architectural
- Biggest business change: <one line>
- Biggest technical change: <one line>
- Risk / action for prod: <one line>
## What Changed
### 1. <Feature / theme>
| | |
|---|---|
| Outcome | <one line> |
| Delivered | <bullet; bullet> |
| Business impact | <one line> |
| Commits | `<hash>` <desc>; `<hash>` <desc> |
### 2. <next theme>
A reader skimming the Outcome rows alone should understand the release.
3 — The shipping flow (where changelog fits)
The roadmap (plans/upcoming/) and the changelog are two ends of one pipe:
plans/upcoming/{critical,now,next,later}.md ── ships ──► changelog/(mmm-yy).md
(what's coming) (what landed)
When something ships:
- Move the line out of the
plans/upcoming/* horizon — don't let shipped work linger there (it kills the roadmap's signal).
- Add / update the entry in the current
changelog/(mmm-yy).md.
- Cross-link: the feature plan's
## What shipped table references the changelog month; the ADR/spec stay linked from the plan.
- If a known bug got fixed, move it from
reviews/bugs/open.md to reviews/bugs/fixed.md with the commit ref.
plans/upcoming/README.md keeps a short "Recently shipped" pointer list to the last few months — pointers only, no restating.
4 — Generating an entry from git
To build a month/release entry, diff the two refs and group commits by theme:
git log --no-merges --pretty='%h %ad %s' --date=short BASE..HEAD
git rev-list --count --no-merges BASE..HEAD
Then: cluster commits into 3–8 themes → write a ### N. Theme block each → fill outcome / delivered / why / commits → write the Executive Summary last (it summarizes the blocks).
5 — Why append-only matters
The changelog is the project's long-term memory. An agent (or a new teammate) that reads the newest one or two month files gets the recent trajectory: what was built, why it mattered, which commits. Editing or pruning old months erases that trail. Superseded decisions are recorded as new lines that reference the old — the history of the change is itself information.
