---
allowed-tools: Read, Write, Edit, Bash, Grep
argument-hint: [version] | --since [tag] | --dry-run
description: Generate changelog entries from git tags using Keep a Changelog format
---

# Generate Changelog

Generate changelog entries from git commits between version tags: $ARGUMENTS

## Current State

- Latest Tag: !`git tag --sort=-creatordate | head -n 1`
- CHANGELOG.md: !`test -f CHANGELOG.md && echo "exists" || echo "does not exist"`
- Commits Since Last Tag: !`git log $(git tag --sort=-creatordate | head -n 1)..HEAD --oneline | wc -l`
- Current Branch: !`git branch --show-current`

## Tasks

### 1. Determine Version Range

**Objective**: Identify the commit range for changelog generation

- [ ] Check if version argument provided
  - If `[version]` provided: Use as the new version number
  - If `--since [tag]` provided: Use custom tag as starting point
  - Otherwise: Use latest tag as starting point

```bash
# Find latest tag
LATEST_TAG=$(git tag --sort=-creatordate | head -n 1)

# Get commits since tag
git log ${LATEST_TAG}..HEAD --oneline

# If no tags exist, use entire history
if [ -z "$LATEST_TAG" ]; then
  git log --oneline
fi
```

**Edge Cases**:
- No tags exist → Use entire commit history and suggest version 0.1.0
- No commits since last tag → Notify user, no changelog needed
- Invalid tag provided → Error with available tags list

### 2. Extract and Categorize Commits

**Objective**: Parse commit messages and group by Keep a Changelog categories

- [ ] Fetch commits with detailed information

```bash
# Get commits with format: hash | date | message
git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%as|%s" --no-merges
```

- [ ] Parse conventional commit patterns and map to categories:

**Mapping Rules**:
- `feat:` or `feature:` → **Added**
- `fix:` or `bugfix:` → **Fixed**
- `refactor:` → **Changed**
- `perf:` or `performance:` → **Changed**
- `docs:` → **Changed** (or skip if only documentation)
- `style:` → **Changed**
- `test:` → (skip from changelog)
- `chore:` → (skip from changelog)
- `build:` or `ci:` → (skip from changelog)
- `revert:` → **Changed** or **Fixed**
- `security:` → **Security**
- `deprecate:` or `deprecated:` → **Deprecated**
- `remove:` or `breaking:` → **Removed**
- Non-conventional commits → **Changed** (default)

- [ ] Extract scope and description from commit messages

**Commit Pattern**: `type(scope): description`

Example:
```
feat(checkout): add reward delivery order support
fix(remission): resolve currency constraint violations
refactor(navigation): implement title management system
```

### 3. Generate Changelog Entry

**Objective**: Create properly formatted changelog section

- [ ] Determine version number
  - Use provided `[version]` argument
  - Or prompt for new version if not provided
  - Format: `[X.Y.Z]` following semantic versioning

- [ ] Get current date in ISO format: `YYYY-MM-DD`

```bash
TODAY=$(date +%Y-%m-%d)
```

- [ ] Build changelog entry following Keep a Changelog format:

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

### Added
- New feature description from feat: commits
- Another feature

### Changed
- Refactored component description
- Performance improvements

### Deprecated
- Feature marked for removal

### Removed
- Deleted feature or breaking change

### Fixed
- Bug fix description
- Another fix

### Security
- Security improvement description
```

**Rules**:
- Only include sections that have entries
- Sort entries alphabetically within each section
- Use sentence case for descriptions
- Remove commit type prefix from descriptions
- Include scope in parentheses if present: `(scope) description`
- Add reference links to commits/PRs if available

### 4. Update or Preview CHANGELOG.md

**Objective**: Append new entry to changelog file or show preview

**If `--dry-run` flag provided**:
- [ ] Display generated changelog entry to stdout
- [ ] Show preview of where it would be inserted
- [ ] Do NOT modify CHANGELOG.md
- [ ] Exit with success

**Otherwise (append mode)**:
- [ ] Check if CHANGELOG.md exists
  - If not, create with standard header:

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

```

- [ ] Read existing CHANGELOG.md content
- [ ] Find insertion point (after "## [Unreleased]" section, or after main header)
- [ ] Insert new changelog entry
- [ ] Maintain reverse chronological order (newest first)
- [ ] Write updated content back to CHANGELOG.md

```bash
# Backup existing file
cp CHANGELOG.md CHANGELOG.md.bak

# Insert new entry
# (Implementation handled by Edit tool)
```

### 5. Validate and Report

**Objective**: Verify changelog quality and provide summary

- [ ] Validate generated entry:
  - Version format is valid (X.Y.Z)
  - Date is correct (YYYY-MM-DD)
  - At least one category has entries
  - No duplicate entries
  - Proper markdown formatting

- [ ] Report statistics:
  - Number of commits processed
  - Entries per category
  - Version number used
  - File status (preview/updated)

- [ ] Show next steps:
  - Review changelog entry
  - Update version in package.json if needed
  - Create git tag if appropriate
  - Commit changelog changes

## Output Format

### Dry Run Preview

```
🔍 Changelog Preview (--dry-run mode)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## [1.5.0] - 2025-10-28

### Added
- (checkout) Add reward delivery order support
- (navigation) Implement title management and tab system

### Changed
- (carousel) Update carousel library implementation
- (remission) Enhance returns processing workflow

### Fixed
- (checkout) Resolve currency constraint violations in price handling

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Statistics
─────────────
Commits processed: 12
Added: 2 entries
Changed: 2 entries
Fixed: 1 entry
Version: 1.5.0
Date: 2025-10-28

⚠️  This is a preview. Run without --dry-run to update CHANGELOG.md
```

### Append Mode Success

```
✅ Changelog Updated Successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## [1.5.0] - 2025-10-28

### Added
- (checkout) Add reward delivery order support
- (navigation) Implement title management and tab system

### Changed
- (carousel) Update carousel library implementation
- (remission) Enhance returns processing workflow

### Fixed
- (checkout) Resolve currency constraint violations in price handling

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Statistics
─────────────
Commits processed: 12
Added: 2 entries
Changed: 2 entries
Fixed: 1 entry
Version: 1.5.0
File: CHANGELOG.md (updated)
Backup: CHANGELOG.md.bak

📋 Next Steps
─────────────
1. Review the changelog entry in CHANGELOG.md
2. Update version in package.json: npm version 1.5.0
3. Commit the changelog: git add CHANGELOG.md && git commit -m "docs: update changelog for v1.5.0"
4. Create git tag: git tag -a v1.5.0 -m "Release v1.5.0"
5. Push changes: git push && git push --tags
```

### Error Cases

```
❌ No Changes Found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
No commits found since last tag (v1.4.5).
Nothing to add to changelog.
```

```
❌ No Tags Found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
No git tags found in this repository.

Suggestions:
- Create your first tag: git tag v0.1.0
- Or specify a commit range: /generate-changelog --since HEAD~10
- Or generate from all commits: /generate-changelog 0.1.0
```

```
⚠️  Invalid Version Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version "1.5" is invalid.
Expected format: X.Y.Z (e.g., 1.5.0)

Please provide a valid semantic version.
```

## References

- Keep a Changelog: https://keepachangelog.com/
- Semantic Versioning: https://semver.org/
- Conventional Commits: https://www.conventionalcommits.org/
- Project Conventions: See CLAUDE.md for commit message standards
