/draft-release-notes - Release Notes Drafting Command for Claude Code

The /draft-release-notes command turns the Conventional Commits made since your last release into clean, grouped release notes following Keep a Changelog, plus a recommended Semantic Versioning bump.

Usage

/draft-release-notes [from-ref]

• With from-ref (a tag or commit): draft notes for everything after that ref.
• Without an argument: use the most recent tag as the starting point.

What it does

When you invoke this command, follow these steps:

1. Find the range. If a from-ref was given, use it. Otherwise resolve the latest tag with git describe --tags --abbrev=0 and fall back to the repository root if there are no tags.
2. Read the commits. Run git log <from-ref>..HEAD --no-merges --pretty=format:%s%x00%b%x00%an to collect each commit's subject, body, and author.
3. Parse Conventional Commits. Classify each subject by its type(scope): prefix. Map types to Keep a Changelog groups: feat → Added, fix → Fixed, perf/refactor → Changed, deprecate → Deprecated, removals → Removed, security fixes → Security. Skip pure docs, style, test, chore, ci, and build commits unless they are user-visible.
4. Detect breaking changes. Treat any type!: marker or BREAKING CHANGE: footer as breaking and list it under a prominent heading.
5. Recommend the bump. Any breaking change → major; otherwise any feat → minor; otherwise patch.
6. Write for humans. Rewrite terse commit subjects into clear, impact-focused bullet points; collapse duplicates; link issue/PR numbers when present.

Output format

## [Unreleased] - proposed vX.Y.Z (<bump> bump)

### Added
- ...

### Fixed
- ...

### Changed
- ...

### Breaking changes
- ...

Requirements

• git available, run from inside the repository.
• A commit history that follows Conventional Commits gives the best grouping; non-conforming commits are listed under a generic "Other" section.

Safety notes

Read-only: the command only reads git history. It does not create tags, commits, or releases, and it does not push — you review and apply the draft yourself.

Privacy notes

Commit subjects, bodies, and author names from the selected range are included in the model's context to draft the notes. If your history contains internal identifiers or unreleased details, review the range before running. Nothing is written to disk by the command.

Source and references

• Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
• Keep a Changelog 1.1.0: https://keepachangelog.com/en/1.1.0/
• Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html