release-notes

Release Notes Generation Skill

Generate professional release notes from git commits between two refs with automated categorization.

Invocation

/release-notes [base] [head] [--version vX.Y.Z] [--output path]

Examples:

# Generate release notes for commits since last tag
/release-notes v1.0.0 HEAD --version v1.1.0

# Compare branches
/release-notes main feature/new-auth --version v2.0.0-beta

# Output to specific file
/release-notes v1.0.0 HEAD --version v1.1.0 --output docs/release-notes/250111-v1.1.0.md

Workflow

Step 1: Parse Commits

Execute the commit parser to extract structured data from git history:

node .claude/skills/release-notes/lib/parse-commits.cjs <base> <head> [--with-files]

Output: JSON with commits array containing:

• hash, shortHash - Commit identifiers
• type, scope, description - Conventional commit parts
• breaking - Boolean for breaking changes
• author, date - Attribution
• files - Changed files (with --with-files flag)

Step 2: Categorize Commits

Pipe parsed commits through the categorizer:

node .claude/skills/release-notes/lib/parse-commits.cjs <base> <head> | \
node .claude/skills/release-notes/lib/categorize-commits.cjs

Categorization Rules:

Excluded Patterns:

• chore(deps): - Dependency updates
• chore(config): - Configuration changes
• [skip changelog] - Explicit skip
• [ci skip] - CI markers

Step 3: Render Markdown

Generate the final release notes document:

node .claude/skills/release-notes/lib/parse-commits.cjs <base> <head> | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0 --output docs/release-notes/250111-v1.1.0.md

Complete Pipeline

For generating release notes in a single command:

# Full pipeline with output to file
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0 --output docs/release-notes/250111-v1.1.0.md

# Pipeline to stdout for review
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0

Advanced Features

Service Boundary Detection

Analyze which services are affected by the release:

# Parse with file changes, then detect services
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD --with-files | \
node .claude/skills/release-notes/lib/detect-services.cjs

Output: Service impact analysis with severity levels (critical, high, medium, low)

Breaking Change Analysis

Enhanced breaking change detection with migration info extraction:

node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/detect-breaking.cjs

Detects:

• BREAKING CHANGE: in commit body
• ! suffix on commit type (e.g., feat!:)
• Migration instructions

PR Metadata Extraction

Extract and link pull request information:

# Extract PR numbers from commit messages
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/extract-pr-metadata.cjs

# With GitHub API enrichment (requires gh CLI)
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/extract-pr-metadata.cjs --fetch-gh

Extracts: PR numbers, titles, labels, authors from commits

Contributor Statistics

Generate detailed contributor stats:

node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/contributor-stats.cjs

Output: Contributor list with commit counts, feature/fix breakdown

Version Bumping

Automatically determine and bump semantic version based on commit types:

# Auto-bump based on commits (feat→minor, fix→patch, BREAKING→major)
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/bump-version.cjs

# Bump with prerelease tag
node .claude/skills/release-notes/lib/bump-version.cjs --prerelease beta

# Per-service versioning
node .claude/skills/release-notes/lib/bump-version.cjs --service platform-core

# Dry run (don't write version file)
node .claude/skills/release-notes/lib/bump-version.cjs --dry-run

Version Files:

• Root: .version
• Per-service: .versions/<service-name>.version

Quality Validation

Validate release notes against quality rules:

# Validate with default threshold (70)
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md

# Custom threshold
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md --threshold 80

# JSON output for CI
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md --json

Validation Rules (100 points total):

LLM-Powered Transforms

Transform release notes for different audiences using Claude API:

# Requires ANTHROPIC_API_KEY environment variable
export ANTHROPIC_API_KEY="your-api-key"

# Create executive summary
node .claude/skills/release-notes/lib/transform-llm.cjs docs/release-notes/v1.1.0.md --transform executive

# Transform for business stakeholders
node .claude/skills/release-notes/lib/transform-llm.cjs docs/release-notes/v1.1.0.md --transform business --output docs/release-notes/v1.1.0-business.md

# Transform for end users
node .claude/skills/release-notes/lib/transform-llm.cjs docs/release-notes/v1.1.0.md --transform enduser

Transform Types:

Full Enhanced Pipeline

Combine all features for comprehensive release notes:

# Enhanced pipeline with service detection
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD --with-files | \
node .claude/skills/release-notes/lib/detect-services.cjs | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/detect-breaking.cjs | \
node .claude/skills/release-notes/lib/contributor-stats.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0

# With version bumping and validation
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD --with-files | \
node .claude/skills/release-notes/lib/bump-version.cjs | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --output docs/release-notes/v1.1.0.md && \
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md

Configuration

See config.yaml for:

• categories - Commit type to section mapping
• services - Service boundary detection by file patterns
• exclude - Patterns to exclude from user-facing notes
• output - Directory and filename format settings

Output Structure

# Release Notes: v1.1.0

**Date:** 2025-01-11
**Version:** v1.1.0
**Status:** Draft

---

## Summary
This release includes 3 new features, 2 improvements, 5 bug fixes.

## What's New
- **Add employee export endpoint** (API)
- **Implement dark mode toggle** (UI)

## Improvements
- **Optimize database queries** (Persistence)

## Bug Fixes
- **Fix date picker timezone issue** (Frontend)
- **Resolve null pointer in auth flow**

## Documentation
- **Update API documentation** (API)

## Breaking Changes
> **Warning**: The following changes may require migration

### Migrate to OAuth 2.1 (Auth)

Legacy JWT tokens no longer accepted.
Migration guide: docs/migrations/oauth-2.1.md

---

## Technical Details
<details>
<summary>For Developers</summary>

### Commits Included
| Hash | Type | Description |
|------|------|-------------|
| abc1234 | feat | Add employee export endpoint |
| def5678 | fix | Fix date picker timezone issue |
...

</details>

## Contributors
- @john.doe
- @jane.smith

---

*Generated with [Claude Code](https://claude.com/claude-code)*

Human Review Gate

Generated release notes are Draft status by default:

1. Review - Check accuracy, add context where needed
2. Enhance - Add migration steps, links, screenshots
3. Approve - Change status to "Released"
4. Publish - Commit and push

Integration with Other Skills

• /commit - After generating notes, commit them
• /git-manager - Create PR for release notes review
• /docs-update - Update CHANGELOG.md with new release

Troubleshooting

No commits found

Verify the refs exist and have commits between them:

git log --oneline <base>..<head>

Non-conventional commits

Commits not following type(scope): description format go to "other" category. Consider running commitlint enforcement.

Missing scope context

Add scope mappings to config.yaml → services section for better context labels.

Task Planning Notes

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed