Changelog Manager

Changelog Manager

When invoked, perform the following changelog management tasks: analyze git history and help update CHANGELOG.md with well-written entries for the [Unreleased] section.

Workflow

Execute these steps in order:

Step 1: Find and Read CHANGELOG.md

1. Look for CHANGELOG.md in the repository root:

   ls -la CHANGELOG.md
   

2. If not found, check common locations or ask the user:

   • docs/CHANGELOG.md
   • CHANGES.md

3. Read the changelog and identify:

   • The last released version (e.g., ## [0.2.0])
   • Existing entries under ## [Unreleased]
   • The changelog format and style used

If no CHANGELOG.md exists, ask the user if they want you to create one.

Step 2: Get Git History Since Last Release (Enhanced)

Path filter note: If a path filter is provided in the prompt (e.g., -- agent-alchemy/sdd/), append it to all git log commands in this step to scope results to that sub-project.

1. Find the tag for the last release:

   git tag --list 'v*' --sort=-version:refname | head -5
   

2. Get commits with extended format including body (for breaking change notices):

   git log v{version}..HEAD --format="%H|%s|%b" --no-merges [path_filter]
   

   If no tags exist, get recent commits with warning:

   git log --format="%H|%s|%b" --no-merges -50 [path_filter]
   

3. Extract PR/issue references for later enrichment:

   git log v{version}..HEAD --no-merges --oneline [path_filter] | grep -oE '#[0-9]+' | sort -u
   

4. For more context on specific commits, use:

   git show --stat {commit_sha}
   

Step 3: Analyze File Changes

Purpose: Understand scope and impact of changes.

Path filter note: If a path filter is provided in the prompt, append it to the git diff commands below to scope results to that sub-project.

1. Get files changed with status (A=Added, M=Modified, D=Deleted, R=Renamed):

   git diff v{version}..HEAD --name-status [path_filter]
   

2. Get summary by directory:

   git diff v{version}..HEAD --dirstat [path_filter]
   

3. Categorize files by area:

   Path Pattern	Category	Changelog Relevance
   src/, lib/	Core code	High
   tests/, __tests__/	Tests	Low (skip)
   docs/, *.md	Documentation	Medium
   Root configs (*.json, *.toml)	Configuration	High
   .github/, CI files	CI/CD	Low (skip)

4. Flag cross-cutting changes: If 5+ directories affected, note "wide-ranging changes" in summary.

Step 4: Deep Diff Analysis

Purpose: Detect API changes and breaking changes.

1. Detect new public interfaces:

   # Python: new functions/classes (public only, skip underscore-prefixed)
   git diff v{version}..HEAD -- "*.py" | grep -E "^\+\s*(def |class )" | grep -v "_"
   
   # JS/TS: new exports
   git diff v{version}..HEAD -- "*.ts" "*.js" | grep -E "^\+.*export"
   

2. Detect removed interfaces (BREAKING):

   # Python
   git diff v{version}..HEAD -- "*.py" | grep -E "^-\s*(def |class )" | grep -v "_"
   
   # JS/TS
   git diff v{version}..HEAD -- "*.ts" "*.js" | grep -E "^-.*export"
   

3. Detect dependency changes:

   git diff v{version}..HEAD -- pyproject.toml package.json requirements*.txt
   

4. Track findings internally:

   • new_apis[] - new public functions/classes
   • removed_apis[] - BREAKING
   • modified_apis[] - potentially breaking
   • dependency_changes[]

Step 5: PR/Issue Context Enrichment

Purpose: Get richer context from PRs and issues.

1. Check gh CLI availability:

   which gh && gh auth status 2>/dev/null
   

2. If gh is available, fetch PR context for each PR number found:

   gh pr view {number} --json title,body,labels,files
   

3. Fallback: If gh unavailable, continue with git data only (log this to user).

4. Extract from PR data:

   • PR title (often better than commit subject)
   • Labels (breaking-change, bug, feature, security)
   • PR body for migration notes

Step 6: Categorize Changes (Enhanced)

Primary: Use conventional commit prefixes:

Secondary signals (override/augment when detected):

For commits without conventional prefixes, use diff analysis results to determine the appropriate category.

Step 7: Synthesize Entries (Enhanced)

Entry sources (priority order):

1. PR title (if more descriptive than commit subject)
2. Commit subject
3. Code analysis (for accuracy)

Entry Format:

• Start with imperative verb (Add, Fix, Change, Remove, etc.)
• Focus on user impact, not implementation details
• Keep entries concise (one line preferred)
• Include scope in parentheses if helpful: Add support for (authentication)

Breaking change format:

### Removed
- **BREAKING**: Remove deprecated `oldFunction` (use `newFunction` instead)

Group related changes when multiple commits touch same feature (>50% file overlap).

Good Examples:

• Add dark mode toggle to settings page
• Fix crash when uploading files larger than 10MB
• Change password requirements to enforce minimum 12 characters
• **BREAKING**: Remove deprecated v1 API endpoints

Poor Examples (avoid):

• Updated code (too vague)
• Fixed bug (doesn't explain what)
• Refactored the authentication module to use dependency injection (too technical)

Step 8: Present Draft for Review (Enhanced)

Show summary stats:

Analyzed N commits since vX.Y.Z:
- Files changed: X (Y core, Z tests)
- New APIs detected: X
- Removed APIs detected: X (BREAKING)
- PR context enriched: X of Y

Prominent breaking changes section (if any detected):

BREAKING CHANGES DETECTED:
- Removed `oldFunction` from module.py
- Changed signature of `processData()`

Show the user:

1. Existing [Unreleased] entries (if any)
2. Suggested new entries organized by category
3. Commits analyzed with brief summary

Prompt the user to choose:

Based on {N} commits since v{version}, I suggest these changelog entries:

### Added
- Entry 1
- Entry 2

### Fixed
- Entry 3

### Changed
- Entry 4

Would you like to:
1. Approve all entries
2. Edit entries (tell me what to change)
3. See detailed analysis
4. See code diffs
5. Skip certain entries

Step 9: Update CHANGELOG.md

Once approved, modify CHANGELOG.md:

1. Add new entries under the appropriate categories in [Unreleased]
2. Create category headings if they don't exist
3. Preserve existing unreleased entries
4. Maintain consistent formatting

Category Order (per Keep a Changelog):

1. Added
2. Changed
3. Deprecated
4. Removed
5. Fixed
6. Security

Sub-project headings: When a scope is provided in the prompt, place entries under a sub-project heading within [Unreleased]:

## [Unreleased]

### sdd

#### Added
- New entry scoped to sdd

### agent-alchemy-tools

#### Fixed
- Fix scoped to agent-alchemy-tools

Use ### for sub-project names and #### for categories within them. If no scope is provided (default behavior), use ### for categories directly as usual — this preserves backward compatibility.

Edge Case Handling

Breaking Change Detection

Auto-flag as BREAKING:

• Removed public function/class/export
• Removed required parameter
• Changed return type of public function
• PR label contains "breaking"
• Commit body contains "BREAKING CHANGE:"

Flag for review (ask user):

• Renamed function/class
• Added required parameter
• Changed default values
• Moved to different module

Quality Standards

• Never add implementation details (commit SHAs, file paths, technical jargon)
• Write from the user's perspective
• Group related changes when possible
• Flag breaking changes prominently with **BREAKING**: prefix
• Maintain the existing changelog's voice and style

Integration Notes

What this component does: Analyzes git history and updates CHANGELOG.md with well-categorized entries following Keep a Changelog format, including breaking change detection and PR enrichment.

Capabilities needed:

• Shell command execution (git commands, gh CLI)
• File reading and editing (CHANGELOG.md)
• Content search (for diff analysis)
• User interaction (entry approval)

Origin: Converted from agent changelog-manager — originally invoked as a sub-agent Complexity hint: Originally ran on a sonnet model Original tool scope: Shell execution, file reading, file editing, file searching, user interaction

Adaptation guidance:

• This skill is self-contained with no external dependencies
• The gh CLI integration (Step 5) is optional and gracefully degrades
• Path filter support allows scoping to monorepo sub-projects