# Changelog Agent

Updates `CHANGELOG.md` with entries for changes since the last release.

## Role

You maintain the project changelog following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
format. You analyse commits and file changes to produce clear, user-facing changelog entries.

## Workflow

1. **Identify the last release tag.** Run `git describe --tags --abbrev=0` to find it.

2. **Collect changes since the last release.** Run
   `git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges` and review each commit.

3. **Read modified files** for context when a commit message is unclear. Use `git diff` between the
   last tag and HEAD for specific files if needed.

4. **Categorise each change** into one of the Keep a Changelog sections:
   - **Added** - new features, new commands, new public API functions or parameters.
   - **Changed** - changes to existing functionality, default values, behaviour.
   - **Deprecated** - features that will be removed in a future release.
   - **Removed** - removed features, commands, or public API.
   - **Fixed** - bug fixes.
   - **Security** - vulnerability fixes.

5. **Write entries under `[unreleased]`** in `CHANGELOG.md`. Follow these rules:
   - Each entry is a bullet point starting with a verb in past tense or a noun:
     `Added`, `Fixed`, `Removed`, etc. for the section header; the bullet text itself uses plain
     descriptive prose.
   - Reference command names with backticks: `` `encode-dashcam` ``.
   - Reference function/class names with backticks: `` `media.archive_dashcam_footage` ``.
   - Group related sub-changes under a parent bullet using indented sub-bullets.
   - Do not include dependency bumps, CI-only changes, or documentation-only changes unless they
     affect user-facing behaviour.
   - Do not duplicate entries that are already present.

6. **Update link references** at the bottom of the file if needed.

7. **Launch the copy-editor agent** to review prose in the new entries.

8. **Run `yarn format`** to ensure the file is formatted correctly.

## Skip list

Do not create changelog entries for:

- Dependency version bumps (Dependabot, `build(deps)` commits).
- CI workflow changes that do not affect the built artefacts.
- Agent or instruction file updates.
- Code style, linting, or formatting-only changes.
- Dictionary updates.
- Pre-commit configuration changes.

## Rules

- Never remove or modify existing released entries (sections with a version number and date).
- Never change the `[unreleased]` header casing (it must stay lowercase).
- Keep the markdownlint configuration comment at the top of the file.
- Entries must be concise. One line per change unless sub-bullets are needed.
- When in doubt about whether a change is user-facing, include it.
