---
description: Initialize or update CHANGELOG.md and RELEASE_NOTES.md from git history
aliases: [ "cl", "change", "release" ]
---

# changelog

Intelligent management of CHANGELOG.md and RELEASE_NOTES.md files through
AI-powered git history analysis.

## Overview

The `/changelog` command provides a comprehensive workflow for maintaining both
developer-focused changelogs and user-facing release notes. It analyzes git
commits, groups related changes, and generates appropriate documentation for
different audiences.

## Usage

```bash
/changelog # Interactive mode - guides you through the process
/changelog init # Initialize both files for the first time
/changelog update # Update files with changes since last update
/changelog review # Review and refine existing entries
/changelog release [version] # Prepare a new release with version bump
```

## Workflow Phases

### Phase 1: Discovery & Analysis

- Detects existing CHANGELOG.md and RELEASE_NOTES.md files
- Identifies last update timestamp from file metadata
- Analyzes repository structure and conventions
- Determines version numbering scheme

### Phase 2: Git History Analysis

- Collects commits since last update (or all if initializing)
- Groups commits by:
    - Feature branches
    - Pull requests
    - Time proximity
    - Semantic similarity
- Identifies breaking changes, features, fixes, and improvements

### Phase 3: Commit Understanding

- For complex or unclear commits:
    - Analyzes code diffs with AI (Sonnet model for accuracy)
    - Extracts semantic meaning from changes
    - Correlates with issue tracker references
    - Identifies user impact

### Phase 4: Change Categorization

- Organizes changes following Keep a Changelog convention:
    - Added: New features
    - Changed: Changes in existing functionality
    - Deprecated: Soon-to-be removed features
    - Removed: Removed features
    - Fixed: Bug fixes
    - Security: Security-related changes

### Phase 5: Documentation Generation

- Creates technical entries for CHANGELOG.md:
    - Comprehensive listing of all changes
    - Technical details and implementation notes
    - References to PRs, issues, and commits
    - Breaking change warnings

- Creates user-focused entries for RELEASE_NOTES.md:
    - High-level feature descriptions
    - User benefits and value propositions
    - Migration guides for breaking changes
    - Screenshots/examples where applicable

### Phase 6: Review & Refinement

- Presents generated content for review
- Allows interactive editing and refinement
- Validates version numbering (semantic versioning)
- Checks for consistency and completeness

### Phase 7: Finalization

- Writes updated files with proper formatting
- Creates git commit for documentation updates
- Tags release if version specified
- Generates release announcement template (optional)

## Interactive Example

```
You: /changelog

Claude: I'll help you manage your changelog and release notes. Let me analyze your repository...

📊 Repository Analysis:
- Found existing CHANGELOG.md (last updated: 2025-11-01)
- Found existing RELEASE_NOTES.md (last updated: 2025-11-01)
- Current version: v2.3.1
- 47 commits since last update

What would you like to do?
1. Update both files with recent changes
2. Prepare a new release (with version bump)
3. Review and refine existing entries
4. Generate release announcement

You: 1

Claude: Analyzing 47 commits since 2025-11-01...

🔍 Identified Changes:
- 3 new features
- 12 improvements
- 8 bug fixes
- 2 breaking changes
- 1 security update

Let me group these semantically and analyze their impact...

[Invokes git-history-analyzer agent]
[Invokes commit-analyst agent for complex changes]
[Invokes changelog-synthesizer agent]

📝 Generated CHANGELOG.md entries:

## [Unreleased]
### Added
- REST API v2 with pagination support (#234, @dev1)
- WebSocket real-time notifications (implements #189)
- Docker compose configuration for local development

### Changed
- **BREAKING:** Updated authentication to use JWT tokens instead of sessions
- Improved database query performance by 40% through indexing
- Migrated from Webpack to Vite for faster builds

### Fixed
- Memory leak in background job processor (#245)
- Incorrect timezone handling in scheduled tasks
- Race condition in concurrent file uploads

### Security
- Updated dependencies to patch CVE-2025-1234

📢 Generated RELEASE_NOTES.md entries:

## What's New

### 🚀 Real-time Notifications
Stay updated with instant WebSocket-powered notifications. No more manual refreshing!

### ⚡ 40% Faster Performance
We've optimized our database queries, making the app significantly more responsive.

### 🔒 Enhanced Security
Upgraded to JWT-based authentication for better security and seamless API access.

### 🐛 Stability Improvements
Fixed several bugs including memory leaks and timezone issues for a smoother experience.

⚠️ **Important:** This update changes how authentication works. You'll need to log in again after updating.

Would you like to:
1. Apply these changes
2. Edit before applying
3. Generate more detailed entries
4. Cancel

You: 1

Claude: ✅ Successfully updated:
- CHANGELOG.md (23 new entries added)
- RELEASE_NOTES.md (4 user-facing updates added)

Created commit: "docs: Update changelog and release notes for unreleased changes"

Next steps:
- Review the updated files
- Consider creating a release with `/changelog release v2.4.0`
- Share release notes with your team
```

## Configuration Options

Create `.changelog.yaml` in your repository root to customize behavior:

```yaml
# Changelog configuration
changelog:
  # Use conventional commits for automatic categorization
  conventional_commits: true

  # Include commit hashes in CHANGELOG.md
  include_commit_hash: true

  # Include author attribution
  include_authors: true

  # Group commits by these criteria
  grouping:
    - pull_request
    - feature_branch
    - semantic_similarity

  # Categories to use (Keep a Changelog format)
  categories:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security

  # Breaking change indicators
  breaking_indicators:
    - "BREAKING CHANGE:"
    - "BREAKING:"
    - "!:" # Conventional commit breaking change

# Release notes configuration
release_notes:
  # Target audience
  audience: "end-users" # or "developers", "stakeholders"

  # Tone
  tone: "professional" # or "casual", "technical"

  # Include screenshots/gifs
  include_visuals: false

  # Emoji usage
  use_emoji: true

  # Maximum entries per category
  max_entries: 5

# Version management
versioning:
  # Semantic versioning strategy
  strategy: "semver" # or "calver", "custom"

  # Auto-bump rules
  auto_bump:
    breaking: "major"
    features: "minor"
    fixes: "patch"

# AI analysis settings
ai_analysis:
  # Model for commit analysis
  model: "claude-4-5-sonnet" # Fast and efficient for code analysis

  # Analyze commits with unclear messages
  analyze_unclear: true

  # Analyze large diffs for better understanding
  analyze_large_diffs: true

  # Threshold for "large" diff (lines changed)
  large_diff_threshold: 100

# Project context integration (NEW - makes RELEASE_NOTES.md more end-user focused)
release_notes:
  # Enable reading CLAUDE.md, README.md, and docs/ for context
  project_context_enabled: true
  project_context_sources:
    - "CLAUDE.md"
    - "README.md"
    - "docs/**/*.md"
  project_context_max_length: 5000
  project_context_cache_ttl_hours: 24

  # Custom instructions (highest priority - override extracted context)
  emphasis_areas: ["Security", "Performance", "User Experience"]
  de_emphasize: ["refactor", "chore", "build", "ci", "deps"]
  include_internal_changes: false  # Exclude internal changes from release notes
  user_impact_keywords: ["user", "customer", "performance", "faster"]
  terminology:
    authentication: "sign-in system"
    API: "developer tools"
```

## Agent Orchestration

**CRITICAL**: You MUST use the Task tool to invoke these agents in sequence. The workflow will fail if you don't invoke agents properly.

### Agent Invocation Sequence

Invoke agents using the Task tool in this exact order:

#### 1. Project Context Extractor (Claude Haiku)

```
Use Task tool with:
- subagent_type: "changelog-manager:project-context-extractor"
- description: "Extract project context from documentation"
- prompt: "Analyze CLAUDE.md, README.md, and docs/ to extract project context, target audience, feature catalog, and tone guidance for generating user-focused release notes."
```

**Purpose**: Reads project documentation to understand product vision, target audience, user personas, and how to translate technical changes into user benefits.

**Output**: Project context object with feature catalog, tone guidance, and custom instructions.

#### 2. Git History Analyzer (Claude Sonnet)

```
Use Task tool with:
- subagent_type: "changelog-manager:git-history-analyzer"
- description: "Analyze git history and group commits"
- prompt: "Extract commits since last update, group by pull request/feature branch/semantic similarity, categorize changes following Keep a Changelog format, and detect breaking changes."
```

**Purpose**: Examines commit history, groups related changes, categorizes them, and identifies breaking changes.

**Output**: Structured change data categorized as Added/Changed/Fixed/etc.

#### 3. GitHub Matcher (Claude Sonnet) - OPTIONAL

```
Only invoke if:
- GitHub remote detected
- gh CLI available and authenticated
- integrations.github.matching.enabled: true in config

Use Task tool with:
- subagent_type: "changelog-manager:github-matcher"
- description: "Match commits to GitHub artifacts"
- prompt: "Enrich commit data with GitHub Issue, PR, Project, and Milestone references using explicit matching, timestamp correlation, and semantic similarity."
```

**Purpose**: Matches commits to GitHub Issues, PRs, Projects, and Milestones using multiple strategies with confidence scoring.

**Output**: Enriched commit data with GitHub artifact references.

#### 4. Changelog Synthesizer (Claude Sonnet)

```
Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Generate changelog documentation"
- prompt: "Generate CHANGELOG.md (technical, developer-focused) and RELEASE_NOTES.md (user-facing, benefits-focused) using project context to translate technical changes into user benefits."
```

**Purpose**: Combines all information to generate both technical and user-facing documentation, using project context to make RELEASE_NOTES.md more end-user focused.

**Output**: Final CHANGELOG.md and RELEASE_NOTES.md content.

### Integration Flow

```
project-context-extractor (Haiku)
         ↓
         ↓ [project_context]
         ↓
git-history-analyzer (Sonnet)
         ↓
         ↓ [git_analysis]
         ↓
github-matcher (Sonnet) [OPTIONAL]
         ↓
         ↓ [enhanced_analysis]
         ↓
changelog-synthesizer (Sonnet)
         ↓
         ↓ [final_documents]
         ↓
    Write files
```

## Agents Used

This command coordinates multiple specialized agents:

- **project-context-extractor**: Reads project documentation (CLAUDE.md, README.md,
  docs/) to understand product vision, target audience, and user-facing features
- **git-history-analyzer**: Examines commit history and groups related changes
- **commit-analyst**: Uses AI to understand complex commits and code changes (invoked automatically by git-history-analyzer when needed)
- **github-matcher**: Matches commits to GitHub Issues, PRs, Projects, and Milestones (optional, only if configured)
- **changelog-synthesizer**: Combines information to generate both technical and
  user-facing documentation, using project context to make RELEASE_NOTES.md more
  end-user focused

## Best Practices

1. **Regular Updates**: Run `/changelog update` frequently (e.g., weekly) to
   avoid large batches
2. **Review Generated Content**: Always review AI-generated entries for accuracy
3. **Maintain Consistency**: Use the same categorization and format across
   releases
4. **Version Strategically**: Follow semantic versioning for clear communication
5. **Separate Audiences**: Keep technical details in CHANGELOG.md, user value in
   RELEASE_NOTES.md

## Tips

- Use `--dry-run` flag to preview changes without writing files
- Run `/changelog review` before releases to ensure quality
- Configure `.changelog.yaml` for project-specific conventions
- Tag releases in git after updating documentation
- Consider automating with git hooks or CI/CD pipelines

## Related Commands

- `/changelog init` - Initialize changelog files for a new project
- `/changelog release` - Prepare a new release with version bump
- `/git-history` - Explore git history in detail
- `/version` - Manage version numbers