Changelog-Update Skill

Update CHANGELOG.md with business-focused entries by systematically reviewing file changes.

Note: For automated release notes from conventional commits, use the release-notes skill instead.

When to Use

• •During development: Document feature/fix for users before PR/merge
• •PR preparation: Add business-focused entry to CHANGELOG.md
• •Manual documentation: When commits don't capture full business impact

Don't use for releases: Use release-notes skill to generate versioned release docs.

Pre-Execution Checklist

1. •

   Find existing CHANGELOG.md location

   • •Check root: ./CHANGELOG.md (preferred)
   • •Fallback: ./docs/CHANGELOG.md
   • •If not found: Create at root
2. •

   Read current changelog to understand format and last entries

Workflow

Step 1: Gather Changes

Determine change scope:

• •PR-based: git diff origin/main...HEAD --name-only
• •Branch-based: git log origin/main..HEAD --oneline
• •Commit-based: git show {commit} --name-only

Step 2: Create Temp Notes File

Create .ai/workspace/changelog-notes-{YYMMDD-HHMM}.md:

# Changelog Review Notes - {date}

## Files Changed
- [ ] file1.ts -
- [ ] file2.cs -

## Categories
### Added (new features)
-

### Changed (modifications to existing)
-

### Fixed (bug fixes)
-

### Deprecated
-

### Removed
-

### Security
-

## Business Summary
<!-- What does this mean for users? -->

Step 3: Systematic File Review

For each changed file:

1. •Read file or diff
2. •Identify business impact (not just technical change)
3. •Check box and note in temp file
4. •Categorize into appropriate section

Business Focus Guidelines:

• •❌ "Added StageCategory enum"
• •✅ "Added stage categories (Sourced, Applied, Interviewing, etc.) for pipeline tracking"
• •❌ "Created PipelineController.cs"
• •✅ "Added API endpoints for pipeline management"

Step 4: Holistic Review

Read temp notes file completely. Ask:

• •What's the main feature/fix?
• •Who benefits and how?
• •What can users now do that they couldn't before?

Step 5: Generate Changelog Entry

Format (Keep a Changelog):

## [Unreleased]

### {Feature/Module Name}: {Feature Title}

**Feature/Fix**: {One-line business description}

#### Added
- {Business-focused item}

#### Changed
- {What behavior changed}

#### Fixed
- {What issue was resolved}

Step 6: Update Changelog

1. •Read existing CHANGELOG.md
2. •Insert new entry under [Unreleased] section
3. •If no [Unreleased] section, create it after the header

Step 7: Cleanup

Delete temp notes file: .ai/workspace/changelog-notes-*.md

Examples

Good Entry

### TextSnippet: Content Management

**Feature**: Rich text snippet management with categorization and search capabilities.

#### Added
- Rich text editor with markdown support
- Category-based organization with tags
- Full-text search across snippets
- Multi-language content support (EN/VI)

Bad Entry (Too Technical)

### Pipeline Changes

#### Added
- Pipeline.cs entity
- StageCategory enum
- PipelineController
- SavePipelineCommand

Anti-Patterns

1. •❌ Creating new changelog in docs/ when root exists
2. •❌ Skipping file review (leads to missed changes)
3. •❌ Technical jargon without business context
4. •❌ Forgetting to delete temp notes file
5. •❌ Not using [Unreleased] section

IMPORTANT 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