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

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

• docs/CHANGELOG.md
• CHANGES.md

1. 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

1. 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]

1. Extract PR/issue references for later enrichment:

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

1. 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]

1. Get summary by directory:

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

1. Categorize files by area:

1. 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"

1. 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"

1. Detect dependency changes:

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

1. 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

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

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

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

1. 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