---
name: "changelog-generator"
description: "Transform raw git commit history into a polished CHANGELOG entry in Keep a Changelog format. Categorizes, rewrites, and suggests the correct semver bump."
metadata:
  version: "1.0.0"
---

# Changelog Generator

> **Purpose:** Transform raw git commit history into a human-readable, user-facing CHANGELOG entry in Keep a Changelog format. Categorizes commits, rewrites them in plain language, and recommends the correct semver version bump.

---

## Invocation

```
/changelog [since-tag]
```

Internally runs:
```bash
git log $(git describe --tags --abbrev=0)..HEAD --format="%H %s" --no-merges
```

If `since-tag` is provided, uses that as the baseline instead of auto-detecting the last tag.

---

## Process

### Step 1: Collect Commits

```bash
git log [since-tag]..HEAD --format="%H|||%s|||%b" --no-merges
```

If no commits found: output "No changes since last release."

---

### Step 2: Categorize by Conventional Commit Prefix

| Prefix | Changelog Section |
|--------|-------------------|
| `feat:` / `feature:` | ### Added |
| `fix:` / `bugfix:` | ### Fixed |
| `perf:` | ### Changed |
| `refactor:` | ### Changed |
| `docs:` | ### Changed |
| `remove:` / `deprecate:` | ### Removed |
| `security:` | ### Security |
| `BREAKING CHANGE` in body | ### Breaking Changes |
| `chore:` / `test:` / `ci:` | **omit** (internal, not user-facing) |

Non-conventional commits: use judgment based on commit message content.

---

### Step 3: Rewrite for Humans

Transform commit messages into user-facing language:
- `fix(auth): resolve JWT expiry edge case` → "Fixed a login session expiry bug that logged users out unexpectedly"
- `feat(dashboard): add export button` → "Added CSV export to the analytics dashboard"
- Group related commits into a single entry if they're part of the same feature

---

### Step 4: Recommend Version Bump

| Condition | Bump |
|-----------|------|
| Only `fix:` commits | Patch (1.0.X) |
| Any `feat:` commit | Minor (1.X.0) |
| Any `BREAKING CHANGE` | Major (X.0.0) |

---

## Output Format

```markdown
## [VERSION] — YYYY-MM-DD

### Breaking Changes
> ⚠️ Migration required: [what users need to change]
- [Breaking change with migration guide]

### Added
- [New feature in plain language] (#PR or commit hash)

### Fixed
- [Bug fixed and user impact explained]

### Changed
- [Improvement with context]

### Removed
- [What was removed and what to use instead]

### Security
- [Vulnerability addressed — always list, never omit]
```

---

## Rules

- Security section must always be listed if any security commit exists — never bury it
- Breaking changes section comes first, always
- Omit `chore:`, `test:`, `ci:` commits — they are not user-facing
- Every entry should explain user impact, not just code change
- If a breaking change has no migration guide: write "Migration guide: [TODO]" — don't omit the section
- Suggest the version number explicitly in the output header