/changelog-composer

name: changelog-composer
description: 'Generates structured changelogs and release notes from git history and PRs, classifying breaking changes, features, fixes, performance, docs. Triggers on: "generate changelog", "write release notes", "what changed since", "prepare release", "release notes for", "diff since tag".'
metadata:
  version: 1.1.1
  category: content
  tags: [changelog, release-notes, git-history, versioning]
  difficulty: intermediate
  phase: ship

Changelog Composer

Transforms raw git history and PR descriptions into polished, audience-appropriate changelogs. Parses conventional commits, classifies changes by impact category, filters internal-only modifications, and produces structured release notes with PR links — following Keep a Changelog conventions.

Reference Files

| File | Contents | Load When | | ------------------------------------ | ------------------------------------------------------------------ | ------------------------------------ | | `references/conventional-commits.md` | Commit type parsing, scope extraction, breaking change indicators | Repository uses conventional commits | | `references/categorization-rules.md` | Change classification logic, audience filtering, severity ordering | Always | | `references/audience-filter.md` | User-facing vs internal change detection, exclusion patterns | Always | | `references/changelog-formats.md` | Keep a Changelog, GitHub Releases, announcement copy templates | Format selection needed |

Prerequisites

• **git** — access to the repository history
• **gh** (optional) — GitHub CLI for PR description extraction
• A tagging strategy (semver tags) for identifying release boundaries

Workflow

Phase 1: Gather Raw Changes

Collect all changes between the previous release and the current state:

1. **Identify boundaries** — Find the last release tag: `git describe --tags --abbrev=0`. If no tags exist, use the initial commit or a user-specified starting point. 2. **Extract commits** — `git log <last-tag>..HEAD --oneline --no-merges` 3. **Extract PR titles** — `gh pr list --state merged --base main --search "merged:>YYYY-MM-DD"` or parse merge commit messages. 4. **Parse conventional commits** — If the repository follows conventional commits (`feat:`, `fix:`, `docs:`, etc.), extract type, scope, and description. See `references/conventional-commits.md`. 5. **Collect breaking change indicators** — Look for `BREAKING CHANGE:` in commit bodies, `!` after type (`feat!:`), or explicit annotations in PR descriptions.

Phase 2: Classify Changes

Categorize each change by its impact:

| Category | Conventional Commit Type | Indicators | | ---------------- | ----------------------------------------------- | ---------------------------------------------- | | Breaking Changes | `feat!:`, `BREAKING CHANGE:` | API removal, signature change, behavior change | | Features | `feat:` | New capability, new endpoint, new command | | Fixes | `fix:` | Bug correction, error handling improvement | | Performance | `perf:` | Speed improvement, memory reduction | | Documentation | `docs:` | README, API docs, guides | | Internal | `chore:`, `ci:`, `refactor:`, `test:`, `build:` | No user-facing impact |

For repositories without conventional commits, classify by reading the commit message and changed files. Code changes to public API → Feature or Fix. Test-only changes → Internal.

Phase 3: Filter for Audience

1. **Exclude internal changes** by default:

• CI/CD configuration changes
• Test additions/modifications
• Dependency bumps (unless security-relevant)
• Code refactoring with no behavior change
• Build system changes

2. **Include internal changes** only when:

• They represent significant architecture shifts users should know about
• They affect development workflow (contributing guide changes)
• The changelog targets developers, not end-users

3. **Highlight breaking changes** prominently — always at the top, always with migration guidance.

Phase 4: Compose Entries

For each included change, write a human-readable description:

1. **Lead with the impact** — "Users can now..." or "Fixed issue where..." 2. **Be specific** — "Reduced memory usage by 40% for large file processing" not "Performance improvements" 3. **Include migration guidance** for breaking changes — what the user must change 4. **Link to source** — PR number, issue number, or commit hash

Phase 5: Output

Assemble the changelog in the requested format, ordered by severity:

1. Breaking Changes (always first) 2. Features 3. Fixes 4. Performance 5. Documentation

Output Format

## [{version}] - {YYYY-MM-DD}

### Breaking Changes
- **`function_name` parameter renamed** — `old_param` is now `new_param`.
  Migration: find/replace `old_param=` with `new_param=` in all call sites. ([#{pr}]({url}))

### Features
- **{Feature name}** — {What it enables and why it matters}. ([#{pr}]({url}))

### Fixes
- Fixed {symptom} when {condition}. ([#{pr}]({url}))

### Performance
- {Operation} is now {X}x faster / uses {X}% less memory. ([#{pr}]({url}))

### Documentation
- Added {guide/reference} for {topic}. ([#{pr}]({url}))

Configuring Scope

| Mode | Input | Output | When to Use | | --------- | -------------------------- | ------------------------ | ----------------------------- | | `