---
description: Add entries for recent commits to CHANGELOG.md (Keep a Changelog format)
argument-hint: [since-ref] | release <version>
allowed-tools:
  - Bash(git describe *)
  - Bash(git log *)
  - Bash(git show *)
  - Bash(git diff *)
  - Bash(git tag *)
  - Read
  - Edit
  - Write
---

Arguments: `$ARGUMENTS`

## Mode

- If the arguments start with `release`, the next word is the version. Go to "Release mode".
- Otherwise, the first argument (if any) is the starting ref. If none, use `git describe --tags --abbrev=0`. If there are no tags, use the root commit and tell the user.

## Collect

1. `git log --format='%H%x09%s%x09%b' <ref>..HEAD` (include merges; PR titles in merge commits are useful).
2. For commits whose subject does not explain the user-visible effect, read `git show --stat <hash>` and the relevant diff.
3. Read existing `CHANGELOG.md`. If it does not exist, create it with:

```
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
```

Only include the Semantic Versioning line if the project's tags look like semver.

## Write entries

- Under `## [Unreleased]`, use these subsections in this order, only when non-empty: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
- One bullet per change, written for someone using or integrating the project: what changed and its effect. Past or present tense consistently with existing entries.
- Append a PR or issue reference like `(#123)` only if it appears in the commit.
- Mark breaking changes with a leading `**Breaking:**` under `Changed` or `Removed` and say what to do.
- Skip: CI, internal refactors with no behavior change, tests, formatting, dependency bumps that do not change behavior (unless security fixes, which go under `Security`).
- Do not duplicate an entry already present in Unreleased.
- Do not edit sections for released versions.

## Release mode

1. Confirm `## [Unreleased]` has entries. If empty, stop and say so.
2. Rename it to `## [<version>] - <today as YYYY-MM-DD>`.
3. Insert a new empty `## [Unreleased]` above it.
4. If the file has link references at the bottom (`[Unreleased]: ...compare/...`), update them following the existing pattern. Otherwise do not add any.
5. Do not create tags or edit version fields in manifests.

## Finish

Show the changed section and a list of skipped commits with a one-line reason each.