repomatic-changelog

name	repomatic-changelog
description	Draft, validate, consolidate, and fix changelog entries.
compatibility	Designed for Claude Code. Recommended model: Sonnet.
allowed-tools	Bash Read Grep Glob Edit Write
argument-hint	[add|check|fix|consolidate [VERSION]|VERSION]

Context

!head -40 changelog.md 2>/dev/null || echo "No changelog.md found" !git log --oneline -10 2>/dev/null ![ -f repomatic/__init__.py ] && echo "CANONICAL_REPO" || echo "DOWNSTREAM"

Instructions

You help users manage their changelog.md file. Follow CLAUDE.md § Changelog and docs updates for style rules.

Mechanical layer

The changelog.yaml workflow's fix-changelog job runs lint-changelog --fix in CI, checking release dates against PyPI, orphaned versions, over-long unreleased bullets, and released sections holding no entry. The check and fix subcommands below invoke the same tool locally. The add subcommand is purely analytical — it reviews git history and drafts entries, which no CI job does.

Determine invocation method

• If the context above shows CANONICAL_REPO, use uv run repomatic.
• Otherwise, use uvx -- repomatic.
• Gate the uvx form with the supply-chain cooldown: uvx --exclude-newer '1 week' --exclude-newer-package repomatic=P0D -- repomatic. The window matches [tool.repomatic] minimum-release-age; repomatic itself is exempt because a fresh release must stay installable, while its dependency tree stays gated. See claude.md § Cooldown on every install.

Argument handling

• (default when $ARGUMENTS is empty): Run add then consolidate on the unreleased section, sequentially.
• add: Review recent git commits and draft changelog entries. Place entries under the current unreleased section. Describe what changed, not how or why: one sentence per user-facing change (~10-25 words), per the canonical entry-length guideline (https://github.com/kdeldycke/repomatic/blob/main/claude.md#changelog-entry-length). Mechanism, internal names, and rationale go in the commit and PR, not the entry.
• check: Run <cmd> lint-changelog and report results. Explain each issue found.
• fix: Run <cmd> lint-changelog --fix and show what was changed.
• consolidate [VERSION]: Consolidate redundant entries in a changelog section. This is analytical work with no CLI equivalent — read the entries, compare against git log for the relevant range, and rewrite. See § Consolidation rules below. If VERSION is omitted, target the unreleased section. If VERSION is given (e.g., consolidate 6.8.0), target that released section instead — locate it in changelog.md by matching the heading, and use the git range between its tag and the previous tag (e.g., v6.7.0..v6.8.0).
• A bare version number (e.g., 6.8.0 or v6.8.0) is shorthand for consolidate VERSION. Strip the v prefix if present.

Consolidation rules

Entries accumulate during development as features are built incrementally. Before release, they need consolidation. The goal is a changelog that reads as a release summary, not a development diary.

1. Read the target section and git log for its range. For the unreleased section, use git log since the last release tag. For a released version like 6.8.0, use git log v6.7.0..v6.8.0 (derive the previous tag from the next heading in changelog.md).
2. Reconcile against the end state, not the commit trail. The changelog records the net diff from the last tag to HEAD. git log includes work that was later undone or superseded, so verify every entry against the current code and docs (open pyproject.toml, the source, the docs) instead of trusting commit messages. Collapse a value that a later commit corrected into its final form: an entry bumping a dependency floor to one version, when a subsequent commit moved it higher, should state the higher version. Drop any change introduced and then reverted within the same cycle: a dependency pinned to a branch until a fix ships and unpinned once it did, or a temporary workaround added then deleted. It never reached a release, so it is a no-op for users.
3. Merge entries that describe the same feature at different stages. Multiple bullets about adding tools to a registry, then migrating workflows for those tools, then wiring up their version pins — that is one feature ("add unified tool runner with 13 managed tools"), not twelve.
4. Merge entries that describe infrastructure and its usage together. "Add binary download infrastructure" + "add 5 binary tools" + "migrate 5 workflow steps" = one bullet covering the feature end-to-end.
5. Keep distinct user-facing changes as separate entries. A breaking config key change and a new CLI command are separate features even if they landed in the same development cycle.
6. Keep the names users need, shed the rest. Tool names, config keys, CLI options, and breaking-change notes stay explicit. But consolidation cuts per-entry length, not just bullet count: a merged entry is one short sentence naming the feature, not a paragraph stacking every mechanism and rationale from the bullets it replaced. Target ~10-25 words (https://github.com/kdeldycke/repomatic/blob/main/claude.md#changelog-entry-length); push implementation detail and "why" to the commit, PR, code comment, or docs/.
7. Remove implementation details that don't affect users: internal refactors, helper functions, test additions. Also strip upstream issue commentary: trailing prose that links to upstream tickets and narrates their status ("Click does not ship an equivalent: the upstream conversation is in (open)…", "mirrors the upstream fix in PR "). The status rots within days and the prose duplicates what the linked thread already says. A bare upstream link is acceptable on a direct backport entry; longer rationale belongs in a code comment, docstring, or PR body.

Style rules

Follow CLAUDE.md § Changelog and docs updates and § Version formatting (bare versions in changelog headings, no v prefix), plus the canonical entry-length guideline (one short sentence per change, what-not-how-or-why): https://github.com/kdeldycke/repomatic/blob/main/claude.md#changelog-entry-length

Next steps

Suggest the user run:

• /repomatic-ship to reconcile the tree and drive the release to a ready-to-merge PR.