Release Notes Writer

---
description: Generate polished release notes from git history between two refs
allowed-tools: Bash(git *), Read, Write
---

# Release Notes Writer

Analyze commits, file changes, and diffs between two git refs and generate polished, audience-appropriate release notes.

The git ref range to analyze: $ARGUMENTS (e.g., `v1.0.0..v1.1.0`, `main~20..main`, or a single tag to compare against HEAD)

## Steps

1. **Parse the ref range** from $ARGUMENTS:
   - If a range like `v1.0..v1.1` is given, use it directly.
   - If a single ref is given, compare that ref to HEAD.
   - If no argument is given, compare the two most recent tags.

2. **Gather git data**:
   - Run `git log <range> --pretty=format:"%h|%s|%an|%ad" --date=short` to get all commits.
   - Run `git diff <range> --stat` to get a summary of file changes.
   - Run `git diff <range> --name-only` to list all changed files.
   - Run `git log <range> --pretty=format:"%s" --grep="Merge pull request\|^feat\|^fix\|^breaking"` to find notable commits.

3. **Categorize changes**:
   Group commits into:
   - **New Features** (`feat:` commits, new files in feature directories)
   - **Bug Fixes** (`fix:` commits)
   - **Breaking Changes** (`BREAKING CHANGE`, major version bumps, removed files)
   - **Performance Improvements** (`perf:` commits)
   - **Developer Experience** (config changes, dependency updates, tooling)
   - **Documentation** (docs changes)

4. **Read key diffs** for context:
   - For each notable commit, read the diff to understand the actual change (not just the commit message).
   - Focus on new exports, new API endpoints, new CLI flags, changed interfaces.

5. **Generate Customer-Facing Changelog**:
   Write benefit-driven release notes for end users:
   - Lead with the most impactful change.
   - Frame each change as a benefit, not a technical description.
   - Example: Instead of "Added Redis caching layer to /api/search", write "Search is now up to 10x faster thanks to intelligent result caching."
   - Include a "Breaking Changes" section with migration steps if applicable.
   - Keep it concise — aim for 200-400 words.

6. **Generate Technical Changelog**:
   Write detailed release notes for developers:
   - List every meaningful change with commit hashes.
   - Include API changes with before/after code examples.
   - Note dependency version bumps.
   - Include migration instructions for breaking changes.

7. **Generate Social Media Snippets**:
   - **Twitter/X post** (under 280 chars): Hook + top feature + link placeholder.
   - **LinkedIn post** (2-3 paragraphs): Professional tone, highlight business value.
   - **Discord/Slack announcement**: Casual tone with emoji, bullet points.

8. **Write the output** to `RELEASE_NOTES.md` in the project root (or print to stdout if the file already exists).

## Rules

- Never fabricate changes that are not in the git history.
- If a commit message is vague (e.g., "fix stuff"), read the diff to understand and describe the actual change.
- Attribute breaking changes prominently — users need to see these first.
- Use semantic versioning context: if this is a minor version, there should be no breaking changes.
- If the range contains more than 200 commits, summarize by category rather than listing individually.