release-notes-generator

Original source / Raw SKILL.md

---
name: release-notes-generator
description: Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use when preparing a production release.
tags: [release-notes, changelog, slack, git, automation]
---

# Release Notes Generator

Generate comprehensive release notes in 3 formats from git commits.

## When to Use This Skill

- Preparing a production release (develop -> main)
- Creating release PR with proper documentation
- Generating Slack announcement for stakeholders
- Updating CHANGELOG.md with new version
- Analyzing commits since last release

## What This Skill Does

1. **Analyzes Git History**: Scans commits since last release tag or specified version
2. **Fetches PR Details**: Gets PR titles, descriptions, and labels via `gh api`
3. **Categorizes Changes**: Groups into features, bug fixes, improvements, security, breaking changes
4. **Generates 3 Outputs**:
   - **CHANGELOG.md section** (technical, complete)
   - **PR Release body** (semi-technical, checklist)
   - **Slack message** (product-focused, user-friendly)
5. **Transforms Language**: Converts technical jargon to accessible messaging
6. **Migration Alert**: Displays prominent warning if database migrations are required

## How to Use

### Basic Usage

```
Generate release notes since last release
```

```
Create release notes for version 0.18.0
```

### With Specific Range

```
Generate release notes from v0.17.0 to HEAD
```

### Preview Only

```
Preview release notes without writing files
```

## Output Formats

### 1. CHANGELOG.md Section

Technical format for developers:

```markdown
## [0.18.0] - 2025-12-08

### Objective
[1-2 sentence summary]

### New Features
#### [Feature Name] (#PR)
- **Description**: ...
- **Impact**: ...

### Bug Fixes
- **[Module]**: Description (#issue, [error-tracker] ISSUE-XX)

### Technical Improvements
#### Performance / UI/UX / Architecture
- [Description]

### Database Migrations
[If applicable]

### Statistics
- PRs: X
- Features: Y
- Bugs: Z
```

### 2. PR Release Body

Uses template from `.github/PULL_REQUEST_TEMPLATE/release.md`:
- Objective summary
- Features with specs links
- Bug fixes with error tracker references
- Improvements by category
- Migration instructions
- Deployment checklist

### 3. Slack Announcement

Product-focused format from `.github/COMMUNICATION_TEMPLATE/slack-release.md`:
- **PR link** included for traceability
- Non-technical language
- Focus on user impact (end-users, admins, stakeholders)
- Emojis for readability
- Statistics summary

## Workflow Integration

This skill integrates with the release workflow:

```
1. Analyze commits: git log <last-tag>..HEAD
2. Determine version number (MAJOR.MINOR.PATCH)
3. Generate 3 outputs
4. Create PR develop -> main with "Release" label
5. Update CHANGELOG.md
6. After merge: create git tag
7. Generate Slack announcement
```

## Tech-to-Product Transformation

The skill automatically transforms technical language:

| Technical | Product |
|-----------|---------|
| "N+1 query optimization with DataLoader" | "Faster list loading" |
| "AI embeddings implementation with pgvector" | "New intelligent search" |
| "Fix scope permissions in getPermissionScope()" | "Fixed access permissions bug" |
| "Migration webpack -> Turbopack" | *Do not communicate* |
| "React hooks refactoring" | *Do not communicate* |
| "Fix N+1 in user loaders" | "Performance improvement" |
| "Add retry logic for DB connection errors" | "Better connection stability" |

## Commit Categories

Commits are categorized by conventional commit prefix:

| Prefix | Category | Include in Slack? |
|--------|----------|-------------------|
| `feat:` | New Features | Yes |
| `fix:` | Bug Fixes | Yes (if user-facing) |
| `perf:` | Performance | Yes (simplified) |
| `security:` | Security | Yes |
| `refactor:` | Architecture | No |
| `chore:` | Maintenance | No |
| `docs:` | Documentation | No |
| `test:` | Tests | No |
| `style:` | Style | No |

## Console Output Format

When generating release notes, ALWAYS display a clear summary in the console with:

### Migration Alert (CRITICAL)

If migrations are detected, display prominently:

```
╔══════════════════════════════════════════════════════════════════╗
║  ⚠️  [WARNING] DATABASE MIGRATIONS REQUIRED                      ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  This release contains X migration(s):                           ║
║                                                                  ║
║  • 20251210123456_add_feature_description                        ║
║  • 20251211094532_update_status_enum                             ║
║                                                                  ║
║  Action required BEFORE deployment:                              ║
║  → Run: [migration-command]                                      ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝
```

If NO migrations:

```
✅ [OK] No database migrations required
```

### Detection Method

Check for new migration files since last release:

```bash
# Find new migrations since last tag
git diff <last-tag>..HEAD --name-only -- migrations/
```

## Example

**User**: "Generate release notes since v0.17.0"

**Output**:

```
Analyzing commits from v0.17.0 to HEAD...

Found:
- 15 commits
- 8 PRs merged
- 2 new features
- 5 bug fixes
- 3 improvements

╔══════════════════════════════════════════════════════════════════╗
║  ⚠️  [WARNING] DATABASE MIGRATIONS REQUIRED                      ║
╠══════════════════════════════════════════════════════════════════╣
║  This release contains 1 migration(s):                           ║
║  • 20251208143021_add_user_preferences                           ║
║  Action required: [migration-command]                             ║
╚══════════════════════════════════════════════════════════════════╝

--- CHANGELOG.md Section ---
[Technical format output]

--- PR Release Body ---
[Semi-technical format output]

--- Slack Announcement ---
[Product-focused format output]

Write to files? (CHANGELOG.md, clipboard for PR/Slack)
```

## Commands Used

```bash
# Get last release tag
git tag --sort=-v:refname | head -n 1

# List commits since tag
git log <tag>..HEAD --oneline --no-merges

# Get PR details
gh api repos/{owner}/{repo}/pulls/{number}

# Get commit details
git show --stat <sha>
```

## Tips

- Run from repository root
- Ensure `gh` CLI is authenticated
- Review generated content before publishing
- Adjust product language for your audience
- Use `--preview` to see output without writing

## Reference Files

- `assets/changelog-template.md` - CHANGELOG section template
- `assets/slack-template.md` - Slack announcement template
- `references/tech-to-product-mappings.md` - Transformation rules
- `references/commit-categories.md` - Categorization rules

## Related Skills

- `github-actions-templates` - For CI/CD workflows
- `changelog-generator` - Original inspiration (ComposioHQ)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### assets/changelog-template.md

```markdown
# CHANGELOG Section Template

Use this template for generating CHANGELOG.md entries.

```markdown
## [X.Y.Z] - YYYY-MM-DD

### Objective
[1-2 sentence summary of this release]

### New Features

#### [Feature Name] (#PR_NUMBER)
- **Description** : [Clear functional description]
- **Spec link** : [Link to spec if available]
- **Impacted components** : `component-a`, `service-b`, etc.
- **Impact** : [Who is affected: End-users / Admins / All]

### Bug Fixes

#### [Module/Component] (#PR_NUMBER)
- **Issue** : [Bug description]
- **Cause** : [Root cause identified]
- **Fix** : [Fix description]
- **[Error tracker]** : PROJECT-XX (if applicable)

### Technical Improvements

#### Performance
- [Optimization description with measurable impact if possible]

#### UI/UX
- [Interface improvement description]

#### Architecture
- [Significant refactoring description]

### Security
- **[CVE-XXXX-XXXXX]** : [Description and impact]

### Database Migrations

#### Deployment Process

**Step 1: Apply migrations**
```bash
[migration-command]
```

**Step 2: Data migration scripts** (if applicable)
```bash
[data-migration-command]
```

**Post-migration verification**
```sql
-- Verification queries
SELECT COUNT(*) FROM [table];
```

### Breaking Changes

**None** or:

- **[Component/API]** : Breaking change description
  - **Migration required** : How to migrate
  - **Impact** : Who is affected

### Deprecations

**None** or:

- **[Feature X]** : Deprecated in this version
  - **Reason** : Why
  - **Alternative** : What to use instead
  - **Planned removal** : Version X.Y.Z

### Tests
- [X] unit tests for [feature]
- [X] integration tests for [module]

### Statistics
- **PRs** : #XX, #YY, #ZZ
- **Files impacted** : XX+
- **New tables** : [list if applicable]
- **Migrations** : X migrations
- **Breaking changes** : 0

### Links
- PR: https://github.com/{owner}/{repo}/pull/XXX
- Included PRs : #XX, #YY, #ZZ
- [Error tracker] issues : PROJECT-XX
```

```

### assets/slack-template.md

```markdown
# Slack Announcement Template

Use this template for generating product-focused Slack messages.

```
Version X.Y.Z - Deployed to production

PR : [Release PR URL, e.g.: https://github.com/{owner}/{repo}/pull/XXX]

In brief : [Sentence describing the main objective of this release]

---

New Features

[Feature Name 1]
> [1-2 sentence description of user impact]
> Who is affected: [End-users / Admins / All]

[Feature Name 2]
> [1-2 sentence description]
> Who is affected: [Roles]

---

Important Fixes

- [Bug fix described in user-friendly language]
- [Bug fix described in user-friendly language]

---

Improvements

- [UX/UI or workflow improvement in user language]
- [...]

---

By the numbers

- X new features
- Y bugs fixed
- Z improvements

---

Questions? Contact @[team-lead] or the dev team
```

## Guidelines

### DO
- Use accessible language (no technical jargon)
- Focus on user impact
- Be concise (max 10 lines per section)
- Use emojis sparingly

### AVOID
- "Implementation of the DataLoader pattern to solve N+1 queries"
- "Complete refactoring of the permissions system with scope ANY/ASSIGNED"
- "Migration from webpack to Turbopack"

### Tech -> Product Transformation

| Technical | Product |
|-----------|---------|
| N+1 query optimization with DataLoader | Faster loading of user and feature lists |
| AI embeddings implementation with pgvector | New intelligent search for similar items |
| Fix scope permissions in getPermissionScope() | Fixed a bug preventing some users from accessing their data |
| Migration to kebab-case for files | *Do not communicate (purely technical)* |
| Fix DB connection with retry logic | Better database connection stability |
| Add error monitoring for orphan records | Automatic detection of orphan records |

### Optional Sections

If the release contains important items, add:

Heads up
- [Important information users should know]
- [Behavior changes they might notice]

Coming soon
- [Teaser for the next big feature]
- [Feature in development coming soon]

```

### references/tech-to-product-mappings.md

```markdown
# Tech-to-Product Transformation Rules

This document defines how to transform technical commit messages into user-friendly product language.

## Transformation Categories

### 1. COMMUNICATE (Transform to product language)

| Technical Pattern | Product Message |
|-------------------|-----------------|
| `N+1 queries`, `DataLoader`, `batching` | "Faster list loading" |
| `embeddings`, `vector search`, `pgvector` | "Improved intelligent search" |
| `permissions`, `scope`, `access control` | "Fixed an access bug" |
| `retry logic`, `resilience`, `connection errors` | "Better connection stability" |
| `SSE`, `real-time`, `WebSocket` | "Real-time updates" |
| `cache`, `memoization` | "Improved performance" |
| `responsive`, `mobile` | "Better mobile experience" |
| `accessibility`, `a11y`, `WCAG` | "Improved accessibility" |
| `monitoring`, `alerting`, `error tracking` | "Better error tracking" |
| `validation`, `sanitization` | "Enhanced security" |

### 2. DO NOT COMMUNICATE (Internal/Technical only)

These patterns should NOT appear in Slack announcements:

| Technical Pattern | Reason |
|-------------------|--------|
| `refactor`, `refactoring` | Internal code quality |
| `webpack`, `turbopack`, `bundler` | Build tooling |
| `eslint`, `prettier`, `linting` | Code style |
| `kebab-case`, `naming convention` | Internal standards |
| `TypeScript`, `type safety` | Developer experience |
| `test`, `spec`, `coverage` | Testing infrastructure |
| `chore`, `maintenance` | Routine maintenance |
| `docs`, `documentation` | Internal docs |
| `deps`, `dependencies`, `bump` | Dependency updates |
| `CI`, `CD`, `workflow` | DevOps infrastructure |

### 3. SECURITY (Always communicate, simplified)

| Technical | Product |
|-----------|---------|
| `CVE-XXXX-XXXXX` | "Fixed a security vulnerability" |
| `XSS`, `injection` | "Enhanced data protection" |
| `authentication`, `auth bypass` | "Improved login security" |
| `CORS`, `CSRF` | "Protection against web attacks" |

## Context-Aware Transformations

### API-related
- "Fix endpoint rate limiting" -> "Improved API stability"
- "Add request validation" -> "Better input handling"
- "Optimize query performance" -> "Faster data loading"

### Dashboard-related
- "Fix dashboard widget rendering" -> "Fixed display issues on dashboard"
- "Add export functionality" -> "New data export feature"
- "Improve chart performance" -> "Faster dashboard loading"

### Notification-related
- "Fix email delivery queue" -> "Improved notification reliability"
- "Add webhook retry logic" -> "More reliable integrations"
- "Optimize notification batching" -> "Faster notification delivery"

### Search-related
- "Fix search indexing race condition" -> "Improved search reliability"
- "Add fuzzy matching" -> "Better search results"
- "Optimize search query execution" -> "Faster search"

## Role-Based Impact

Always specify who is affected:

| Impact | Roles |
|--------|-------|
| Dashboard changes | End-users, Admins |
| API changes | End-users, Power users |
| Admin panel | Admins only |
| Billing/Payment | Admins, Stakeholders |
| Reports/Analytics | Admins, Power users |
| Notifications | All users |
| Search | All users |

## Severity Indicators

Use these prefixes when appropriate:

- **Critical** : Production-blocking issues
- **Important** : User-facing bugs
- **Minor** : Quality of life improvements
- *Do not mention* : Internal fixes

```

### references/commit-categories.md

```markdown
# Commit Categorization Rules

This document defines how to categorize commits based on Conventional Commits format.

## Primary Categories

### Features (`feat:`)
**CHANGELOG**: New Features
**Slack**: Yes - always include
**Examples**:
- `feat(dashboard): add export report system`
- `feat(search): add fuzzy matching`
- `feat(api): add batch operations endpoint`

### Bug Fixes (`fix:`)
**CHANGELOG**: Bug Fixes
**Slack**: Yes - if user-facing; No - if internal
**Examples**:
- `fix(auth): correct token refresh flow` -> Include in Slack
- `fix(test): correct mock setup` -> Do NOT include in Slack

### Performance (`perf:`)
**CHANGELOG**: Technical Improvements > Performance
**Slack**: Yes - simplified ("Performance improvement")
**Examples**:
- `perf(api): optimize N+1 queries with batching`
- `perf(build): reduce bundle size by 30%`

### Security (`security:` or `fix(security):`)
**CHANGELOG**: Security
**Slack**: Yes - always, with appropriate detail level
**Examples**:
- `security: fix CVE-2025-55182 dependency RCE`
- `fix(security): prevent XSS in user input`

## Secondary Categories (CHANGELOG only)

### Refactoring (`refactor:`)
**CHANGELOG**: Technical Improvements > Architecture
**Slack**: No
**Examples**:
- `refactor(hooks): migrate to new pattern`
- `refactor(permissions): extract to service layer`

### Documentation (`docs:`)
**CHANGELOG**: Documentation (if significant)
**Slack**: No
**Examples**:
- `docs: update CLAUDE.md with new patterns`
- `docs(api): add endpoint documentation`

### Tests (`test:`)
**CHANGELOG**: Tests (count only)
**Slack**: No
**Examples**:
- `test(api): add endpoint integration tests`
- `test(e2e): add workflow tests`

### Chores (`chore:`)
**CHANGELOG**: No (unless significant)
**Slack**: No
**Examples**:
- `chore: update dependencies`
- `chore(ci): fix workflow permissions`

### Style (`style:`)
**CHANGELOG**: No
**Slack**: No
**Examples**:
- `style: apply prettier formatting`
- `style(eslint): fix linting errors`

## Scope Patterns

Common scopes:

| Scope | Area |
|-------|------|
| `auth` | Authentication |
| `billing` | Billing and payments |
| `api` | API endpoints |
| `ui` | UI components |
| `dashboard` | Dashboard features |
| `notifications` | Notification system |
| `search` | Search functionality |
| `user` | User management |
| `db` | Database and migrations |
| `permissions` | Permission system |
| `admin` | Admin panel |

## Breaking Changes

Indicated by `!` after type/scope or `BREAKING CHANGE:` in footer:
- `feat(api)!: change status enum`
- `fix(auth)!: require new token format`

**CHANGELOG**: Breaking Changes section
**Slack**: Yes - with migration instructions

## PR Number Extraction

Extract PR numbers from:
1. Commit message: `(#123)`
2. Merge commit: `Merge pull request #123`
3. GitHub API: cross-reference with commit SHA

## Error Tracker Issue Linking

Match patterns:
- `[error-tracker]: PROJECT-XX`
- `fixes PROJECT-XX`
- `closes #XX` (GitHub issue)

## Statistics Calculation

Count for release stats:
- **PRs**: Unique PR numbers
- **Features**: `feat:` commits
- **Bugs**: `fix:` commits (excluding test/internal)
- **Improvements**: `perf:` + `refactor:` + UI improvements
- **Security**: `security:` commits
- **Breaking**: Commits with `!` or `BREAKING CHANGE`

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### assets/README.md

```markdown
# Assets

This directory contains templates, images, and boilerplate code.

**Note**: Assets are NOT automatically loaded into context. They must be explicitly referenced.

## Guidelines

- Use descriptive filenames
- Include usage instructions in file headers
- Keep templates minimal and customizable

## Files

Add your assets here. Examples:
- `template.md` - Output template
- `boilerplate.ts` - Code boilerplate
- `config.json` - Configuration template

```

### references/README.md

```markdown
# References

This directory contains documentation that will be loaded contextually during skill execution.

## Guidelines

- Keep files focused and well-organized
- Use markdown format for readability
- Include concrete examples where possible
- Update when domain knowledge changes

## Files

Add your reference documents here. Examples:
- `api-docs.md` - API documentation
- `style-guide.md` - Formatting guidelines
- `domain-knowledge.md` - Domain-specific information

```

### scripts/README.md

```markdown
# Scripts

This directory contains executable scripts for deterministic, repeatable tasks.

## Guidelines

- Scripts should be self-contained and well-documented
- Include usage examples in script headers
- Handle errors gracefully with clear messages
- Use appropriate exit codes (0 for success, 1 for failure)

## Files

Add your scripts here. Examples:
- `generate.py` - Main generation script
- `validate.py` - Validation utilities
- `transform.py` - Data transformation helpers

```