Changelog Update

Changelog-Update Skill

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

Summary

Goal: Update CHANGELOG.md [Unreleased] section with business-focused entries via systematic file review.

Key Principles:

• Business-focused language, not technical jargon (what users can do, not what classes were added)
• For automated release notes from conventional commits, use release-notes skill instead
• Always delete temp notes file after completion

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

Keep a Changelog Format Reference

Based on Keep a Changelog v1.1.0

Core Principles

1. Written by humans, for humans - Changelogs must be readable by both technical and non-technical audiences 2. Latest changes first - Most recent versions appear at the top 3. One entry per version - Each version has its own section 4. ISO 8601 date format - Use YYYY-MM-DD format (e.g., 2026-01-14) 5. Semantic Versioning - Follow SemVer for version numbers

Format Structure

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features go here

### Changed
- Changes in existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Now removed features

### Fixed
- Bug fixes

### Security
- Security vulnerability fixes

## [1.0.0] - 2026-01-14

### Added
- Initial release features

[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0

Entry Types

Added

For new features.

Example:

- Drag-and-drop pipeline builder with customizable stages
- User authentication with OAuth 2.0 support

Changed

For changes in existing functionality.

Example:

- Updated dashboard layout for better mobile experience
- Improved performance of data loading by 50%

Deprecated

For soon-to-be removed features.

Example:

- Legacy API v1 endpoints (will be removed in v3.0.0)

Removed

For now removed features.

Example:

- Removed deprecated v1 authentication endpoints

Fixed

For any bug fixes.

Example:

- Fixed user profile not loading when session expires
- Corrected calculation error in monthly reports

Security

For security vulnerability fixes.

Example:

- Patched SQL injection vulnerability in search endpoint
- Updated dependencies to fix CVE-2026-12345

Version Format

• [Unreleased] - For changes not yet released
• [MAJOR.MINOR.PATCH] - For released versions following Semantic Versioning
• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Examples:

• [2.0.0] - Breaking changes
• [1.5.0] - New features
• [1.4.3] - Bug fix

Date Format

Always use ISO 8601 format: YYYY-MM-DD

Examples:

• 2026-01-14
• 2025-12-31

Links Section

At the bottom of the changelog, include comparison links:

[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0

Best Practices

1. Group related changes - Organize entries by feature/module 2. Be concise but informative - One line per change, clear description 3. Focus on impact - Explain what users gain or what behavior changes 4. Avoid technical jargon - Write for all audiences 5. Reference issues/PRs - Link to more details when helpful 6. Maintain chronological order - Latest first within each section

Business-Focused Writing

Transform technical changes to user value:

Common Mistakes to Avoid

1. ❌ Using commit messages directly as changelog entries 2. ❌ Mixing technical and business language inconsistently 3. ❌ Forgetting to update [Unreleased] section during development 4. ❌ Not grouping related changes together 5. ❌ Omitting dates from version headers 6. ❌ Using non-standard date formats

References

• Official specification: Keep a Changelog v1.1.0
• Semantic Versioning: SemVer 2.0.0
• Common Changelog: common-changelog.org