tomevault-io [IMPORTANT] Use
TaskCreateto break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.
Quick Summary
Goal: Generate professional release notes from git commits with automated categorization, service detection, and validation.
Workflow:
- Parse Commits —
parse-commits.cjs <base> <head>extracts structured data from git - Categorize — Pipe through
categorize-commits.cjsfor user-facing vs internal sections - Render —
render-template.cjs --version vX.Y.Zgenerates markdown with Summary, What's New, Improvements, Bug Fixes, Breaking Changes, Technical Details
Key Rules:
- Pipeline: parse → categorize → render → validate → transform
- Advanced: Service detection, breaking change analysis, PR metadata, contributor stats, version bumping
- Human Review: Generated notes are Draft status, require review/enhance/approve before publish
- Validation:
validate-notes.cjsscores against quality rules (100 points)
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Release Notes Generation Skill
Generate professional release notes from git commits between two refs with automated categorization.
Invocation
/release-notes [base] [head] [--version vX.Y.Z] [--output path]
Examples:
# Generate release notes for commits since last tag
/release-notes v1.0.0 HEAD --version v1.1.0
# Compare branches
/release-notes main feature/new-auth --version v2.0.0-beta
# Output to specific file
/release-notes v1.0.0 HEAD --version v1.1.0 --output docs/release-notes/250111-v1.1.0.md
Workflow
Step 1: Parse Commits
Execute the commit parser to extract structured data from git history:
node .claude/skills/release-notes/lib/parse-commits.cjs <base> <head> [--with-files]
Output: JSON with commits array containing:
hash,shortHash- Commit identifierstype,scope,description- Conventional commit partsbreaking- Boolean for breaking changesauthor,date- Attributionfiles- Changed files (with--with-filesflag)
Step 2: Categorize Commits
Pipe parsed commits through the categorizer:
node .claude/skills/release-notes/lib/parse-commits.cjs <base> <head> | \
node .claude/skills/release-notes/lib/categorize-commits.cjs
Categorization Rules:
| Type | Category | User-Facing |
|---|---|---|
feat |
features | Yes |
fix |
fixes | Yes |
perf |
improvements | Yes |
docs |
docs | Yes (unless internal) |
refactor |
improvements | Technical only |
test, ci, build, chore, style |
internal | No |
Excluded Patterns:
chore(deps):- Dependency updateschore(config):- Configuration changes[skip changelog]- Explicit skip[ci skip]- CI markers
Step 3: Render Markdown
Generate the final release notes document:
node .claude/skills/release-notes/lib/parse-commits.cjs <base> <head> | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0 --output docs/release-notes/250111-v1.1.0.md
Complete Pipeline
For generating release notes in a single command:
# Full pipeline with output to file
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0 --output docs/release-notes/250111-v1.1.0.md
# Pipeline to stdout for review
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0
Advanced Features
Service Boundary Detection
Analyze which services are affected by the release:
# Parse with file changes, then detect services
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD --with-files | \
node .claude/skills/release-notes/lib/detect-services.cjs
Output: Service impact analysis with severity levels (critical, high, medium, low)
Breaking Change Analysis
Enhanced breaking change detection with migration info extraction:
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/detect-breaking.cjs
Detects:
BREAKING CHANGE:in commit body!suffix on commit type (e.g.,feat!:)- Migration instructions
PR Metadata Extraction
Extract and link pull request information:
# Extract PR numbers from commit messages
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/extract-pr-metadata.cjs
# With GitHub API enrichment (requires gh CLI)
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/extract-pr-metadata.cjs --fetch-gh
Extracts: PR numbers, titles, labels, authors from commits
Contributor Statistics
Generate detailed contributor stats:
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/contributor-stats.cjs
Output: Contributor list with commit counts, feature/fix breakdown
Version Bumping
Automatically determine and bump semantic version based on commit types:
# Auto-bump based on commits (feat→minor, fix→patch, BREAKING→major)
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD | \
node .claude/skills/release-notes/lib/bump-version.cjs
# Bump with prerelease tag
node .claude/skills/release-notes/lib/bump-version.cjs --prerelease beta
# Per-service versioning
node .claude/skills/release-notes/lib/bump-version.cjs --service {service-name}
# Dry run (don't write version file)
node .claude/skills/release-notes/lib/bump-version.cjs --dry-run
Version Files:
- Root:
.version - Per-service:
.versions/<service-name>.version
Quality Validation
Validate release notes against quality rules:
# Validate with default threshold (70)
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md
# Custom threshold
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md --threshold 80
# JSON output for CI
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md --json
Validation Rules (100 points total):
| Rule | Weight | Description |
|---|---|---|
| summary_exists | 15 | Has Summary section |
| summary_not_empty | 10 | Summary has content |
| has_version | 10 | Version number present |
| features_documented | 10 | Features properly formatted |
| fixes_documented | 10 | Bug fixes properly formatted |
| no_broken_links | 10 | No empty link references |
| contributors_listed | 10 | Contributors section present |
| has_date | 5 | Date present |
| no_todo_markers | 5 | No TODO/FIXME markers |
| proper_heading_hierarchy | 5 | Proper H1→H2 structure |
| no_placeholder_text | 5 | No placeholder text |
| technical_details_collapsed | 5 | Tech details in |
LLM-Powered Transforms
Transform release notes for different audiences using Claude API:
# Requires ANTHROPIC_API_KEY environment variable
export ANTHROPIC_API_KEY="your-api-key"
# Create executive summary
node .claude/skills/release-notes/lib/transform-llm.cjs docs/release-notes/v1.1.0.md --transform executive
# Transform for business stakeholders
node .claude/skills/release-notes/lib/transform-llm.cjs docs/release-notes/v1.1.0.md --transform business --output docs/release-notes/v1.1.0-business.md
# Transform for end users
node .claude/skills/release-notes/lib/transform-llm.cjs docs/release-notes/v1.1.0.md --transform enduser
Transform Types:
| Type | Description |
|---|---|
summarize |
Brief 3-5 bullet point summary |
business |
ROI-focused, business language |
enduser |
User-friendly, non-technical |
executive |
Strategic impact summary |
technical |
Enhanced technical details |
Full Enhanced Pipeline
Combine all features for comprehensive release notes:
# Enhanced pipeline with service detection
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD --with-files | \
node .claude/skills/release-notes/lib/detect-services.cjs | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/detect-breaking.cjs | \
node .claude/skills/release-notes/lib/contributor-stats.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --version v1.1.0
# With version bumping and validation
node .claude/skills/release-notes/lib/parse-commits.cjs v1.0.0 HEAD --with-files | \
node .claude/skills/release-notes/lib/bump-version.cjs | \
node .claude/skills/release-notes/lib/categorize-commits.cjs | \
node .claude/skills/release-notes/lib/render-template.cjs --output docs/release-notes/v1.1.0.md && \
node .claude/skills/release-notes/lib/validate-notes.cjs docs/release-notes/v1.1.0.md
Configuration
See config.yaml for:
- categories - Commit type to section mapping
- services - Service boundary detection by file patterns
- exclude - Patterns to exclude from user-facing notes
- output - Directory and filename format settings
Output Structure
# Release Notes: v1.1.0
**Date:** 2025-01-11
**Version:** v1.1.0
**Status:** Draft
---
## Summary
This release includes 3 new features, 2 improvements, 5 bug fixes.
## What's New
- **Add employee export endpoint** (API)
- **Implement dark mode toggle** (UI)
## Improvements
- **Optimize database queries** (Persistence)
## Bug Fixes
- **Fix date picker timezone issue** (Frontend)
- **Resolve null pointer in auth flow**
## Documentation
- **Update API documentation** (API)
## Breaking Changes
> **Warning**: The following changes may require migration
### Migrate to OAuth 2.1 (Auth)
Legacy JWT tokens no longer accepted.
Migration guide: docs/migrations/oauth-2.1.md
---
## Technical Details
<details>
<summary>For Developers</summary>
### Commits Included
| Hash | Type | Description |
| ------- | ---- | ------------------------------ |
| abc1234 | feat | Add employee export endpoint |
| def5678 | fix | Fix date picker timezone issue |
...
</details>
## Contributors
- @john.doe
- @jane.smith
---
_Generated with [Claude Code](https://claude.com/claude-code)_
Human Review Gate
Generated release notes are Draft status by default:
- Review - Check accuracy, add context where needed
- Enhance - Add migration steps, links, screenshots
- Approve - Change status to "Released"
- Publish - Commit and push
Integration with Other Skills
/commit- After generating notes, commit them/git-manager- Create PR for release notes review/docs-update- Update CHANGELOG.md with new release
Troubleshooting
No commits found
Verify the refs exist and have commits between them:
git log --oneline <base>..<head>
Non-conventional commits
Commits not following type(scope): description format go to "other" category. Consider running commitlint enforcement.
Missing scope context
Add scope mappings to config.yaml → services section for better context labels.
Closing Reminders
- IMPORTANT MUST ATTENTION break work into small todo tasks using
TaskCreateBEFORE starting - IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
- IMPORTANT MUST ATTENTION cite
file:lineevidence for every claim (confidence >80% to act) - IMPORTANT MUST ATTENTION add a final review todo task to verify work quality
Converted and distributed by TomeVault — claim your Tome and manage your conversions.