Changelog Writer

---
name: changelog-writer
description: |
  Trigger when the user asks to write a CHANGELOG entry, draft release
  notes from commits, or document what shipped. Phrases: "write changelog",
  "changelog entry", "what shipped", "document the release", "update
  CHANGELOG.md".
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(git log *)
  - Bash(git diff *)
  - Bash(git tag *)
---

# Changelog Writer

Turn commits and PRs into a CHANGELOG.md entry that humans actually read.
Follows Keep a Changelog conventions and groups by audience impact, not
commit subject.

## Prerequisites

- `CHANGELOG.md` exists (create one if missing, starting with an
  `## [Unreleased]` section)
- Git history is readable (`git log` returns commits since last tag)
- Previous version tag exists, or user specifies the range

## Steps

1. **Find the range.** Default: last tag to HEAD.
   ```bash
   git describe --tags --abbrev=0    # last tag
   git log <last-tag>..HEAD --oneline
   ```

2. **Group by Keep a Changelog categories:**
   - **Added** - new features users can see
   - **Changed** - behavior changes to existing features
   - **Deprecated** - soon-to-be-removed features
   - **Removed** - features taken out
   - **Fixed** - bug fixes
   - **Security** - vulnerabilities patched

3. **Write for the reader, not the committer.** "Bumped lodash to 4.17.21"
   is not a changelog entry. "Fixed XSS vulnerability in search
   autocomplete (CVE-2024-xxxx)" is.

4. **One line per entry, user perspective.** Start with a verb, link the
   PR or issue, and mention breaking changes with a **BREAKING** prefix.

5. **Follow semver signals.** If you see breaking API changes, plan for a
   major bump. New features = minor. Fixes and internal refactors = patch.

6. **Version header format:**
   ```markdown
   ## [1.4.0] - 2026-04-22

   ### Added
   - Dark mode toggle in settings ([#412](link))
   - Webhook retry with exponential backoff

   ### Fixed
   - Timezone bug in daily digest emails ([#401](link))

   ### Changed
   - **BREAKING** \`createUser()\` now requires an \`email\` field
   ```

7. **Link the compare view at the bottom:**
   ```markdown
   [1.4.0]: https://github.com/org/repo/compare/v1.3.0...v1.4.0
   ```

8. **Skip the noise.** Filter out: `chore:`, `ci:`, dependency bumps
   that are not security fixes, test-only commits, formatting. These
   belong in git history, not the changelog.

## Patterns that work

- Draft as `## [Unreleased]` continuously, promote to a version on release
- Pull from merged PR titles and descriptions, not raw commit messages
- Include migration notes inline for any breaking change
- Attribute external contributors with a GitHub handle link

## Anti-patterns

- Dumping `git log --oneline` output and calling it done
- Listing internal refactors ("Refactor UserService")
- Writing for developers when the audience is end users
- Forgetting to date the release

## Output

- Updated `CHANGELOG.md` with a new version section
- `## [Unreleased]` section reset for future entries
- Version compare links at the bottom of the file
- Optional: a tweet-length summary for release announcements