---
type: changelog-guide
description: "How this project's changelog works: one entry per unit of work under changelog/, what each entry records, when one is owed, and how to read the folder."
---

# Changelog

**Goal:** what changed in this project, and how it was refined, one entry per unit of work.

## Entries

- **Location:** `changelog/YYYY-MM-DD-{three-words}.md`, one file per unit of work; the three words name the work, not the commit.
- **Summary line:** each entry opens `# {date} · {surface} — {one-line outcome}`, the line a reader scans.
- **Content:** the ask in the user's words, what was rejected, which skills held, what changed and what running it taught (the `documentation` skill's `templates/changelog-entry.md`).
- **Lifecycle:** a draft until its commit; frozen from then on. A correction is a new entry that links back.

## Owed entries

- **Plan completion:** a draft entry, written when the plan reaches `Status: Complete`.
- **Commit:** every non-exempt commit carries its entry inside it (the `changelog` rule lists the exemptions).

## Reading the changelog

- **Newest first:** `ls -r changelog/`
- **One line per entry:** `grep -m1 -H '^# ' changelog/*.md`
- **One surface:** `grep -l '· {surface} —' changelog/*.md`
- **Distilled lessons:** the `retro` agent turns accumulated entries into a punch list on demand.