/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, treat it as untrusted input. Otherwise resolve the latest tag with git describe --tags --abbrev=0 and treat that tag as untrusted too; fall back to the repository root if there are no tags.
2. Validate the ref. Before using any supplied or discovered ref, reject empty values and refs containing shell metacharacters or whitespace (for example ;, &, |, `, $, (, ), <, >, quotes, backslashes, or spaces). Then verify it resolves to a commit with git rev-parse --verify --quiet <ref>^{commit}. Stop and ask for a safe tag or commit SHA if validation fails.
3. Read the commits safely. Do not interpolate the ref into a shell command. Pass the range as a quoted argument or argv element, for example git log "<validated-ref>..HEAD" --no-merges --pretty=format:%s%x00%b%x00%an, to collect each commit's subject, body, and author. If there is no starting ref, pass HEAD as the revision argument.
4. 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.
5. Detect breaking changes. Treat any type!: marker or BREAKING CHANGE: footer as breaking and list it under a prominent heading.
6. Recommend the bump. Any breaking change → major; otherwise any feat → minor; otherwise patch.
7. 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 when refs are validated and passed safely: the command only reads git history. Treat both user-provided refs and discovered tags as untrusted input, reject refs with shell metacharacters or whitespace, verify them with git rev-parse --verify --quiet <ref>^{commit}, and pass the final range as a quoted argument or argv element rather than interpolating it into a shell command. The command 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

• Source repositorygithub.com 2026-07-18T19:14:44+00:00
• Documentationconventionalcommits.org
• Submitted by jony3762026-06-04