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]

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/

git log

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

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:

feat:

fix:

refactor:

change:

perf:

security:

deprecate:

remove:

docs:

chore:

test:

ci:

style:

build:

Secondary signals (override/augment when detected):

breaking-change

security

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

###

####

###

Edge Case Handling

--no-merges

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

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