Changelog

Changelog Skill

Generate business-focused changelog entries by systematically reviewing file changes.

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 based on mode:

# PR/Branch-based (default)
git diff origin/develop...HEAD --name-only

# Commit-based
git show {commit} --name-only

# Range-based
git diff {from}..{to} --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:

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]

### {Module}: {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 header
4. Preserve existing entries

Step 7: Cleanup

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

Grouping Strategy

Group related changes by module/feature:

### Your Service: Hiring Process Management

**Feature**: Customizable hiring process/pipeline management.

#### Added

**Backend**:

- Entities: Pipeline, Stage, PipelineStage
- Controllers: PipelineController, StageController
- Commands: SavePipelineCommand, DeletePipelineCommand

**Frontend**:

- Pages: hiring-process-page
- Components: pipeline-filter, pipeline-stage-display

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
6. ❌ Listing every file instead of grouping by feature

Examples

Good Entry

### Your Service: Hiring Process Management

**Feature**: Customizable hiring process/pipeline management for recruitment workflows.

#### Added

- Drag-and-drop pipeline stage builder with default templates
- Stage categories (Sourced, Applied, Interviewing, Offered, Hired, Rejected)
- Pipeline duplication for quick setup
- Multi-language stage names (EN/VI)

#### Changed

- Candidate cards now show current pipeline stage
- Job creation wizard includes pipeline selection

Bad Entry (Too Technical)

### Pipeline Changes

#### Added

- Pipeline.cs entity
- StageCategory enum
- PipelineController
- SavePipelineCommand
- 20251216000000_MigrateDefaultStages migration

Reference

See references/keep-a-changelog-format.md for format specification.

Related

• documentation
• release-notes
• commit

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks
• Always add a final review todo task to verify work quality and identify fixes/enhancements