| name | changelog-update |
| description | Update CHANGELOG.md and usr/docs/changelogs in amkisko house style. Use when editing changelogs, preparing releases, or syncing engineering notes into product-facing release text. |
Changelog update
Two layers
usr/docs/changelogs/ — engineering draft: intent, reproduction steps, implementation notes, pull request links.CHANGELOG.md — product-facing release notes: describe what people see and can do, not how it is built.
File name for new engineering notes: usr/docs/changelogs/#{YYYYMMDDHHMMSS}_<title>.md with kebab-case title.
Audience split
| Layer | Reader | Voice |
|---|
CHANGELOG.md | users, operators, product owners | outcome, screen, workflow; plain language |
usr/docs/changelogs/ | engineers and reviewers | classes, files, trade-offs, links |
CHANGELOG.md may name an operator surface when that is the user-visible place, but still describe the workflow benefit, not internal adapter or job names.
When to write
- user-visible features, fixes, and breaking behavior: yes;
- library upgrades, internal refactors, dev-only tooling: no unless they change a public contract or operator workflow users rely on;
- do not invent behavior; gather facts from
usr/docs/changelogs/, git diff, or commits since the last release tag.
CHANGELOG.md shape
# CHANGELOG
## X.Y.Z (YYYY-MM-DD)
- Add ...
- Fix ...
Rules:
- title line is
# CHANGELOG only;
- use ISO date in parentheses on version headings when the repository follows that convention;
- unordered list with
- only;
- bullets stay imperative, concrete, and short;
- no marketing language;
- no negation-first hooks.
Workflow
- capture engineering detail in
usr/docs/changelogs/ when the change is significant enough to mention;
- distill user-visible outcomes into
CHANGELOG.md when cutting a release;
- read once for marketing odor, once for negation-led sentences, once for stray em dashes;
- keep version headings and release tags aligned when the repository uses tagged releases.
Relationship to pull requests
Pull request descriptions answer what problem is solved, why it matters, how the solution works, and relevant context. Changelog bullets are slightly more user-facing than commit titles but still concrete, not promotional.
