pr Release Notes Architect

The Problem

You merge a PR with 15 commits and need to write the PR description, the GitHub Release notes, and the CHANGELOG.md entry. You open the PR diff and see a wall of file changes — some are features, some are fixes, one is a breaking change buried in a refactor commit. You write a two-line PR description that says "adds rate limiting and fixes some bugs." The release manager asks what broke and you can't remember. The changelog entry you publish omits the performance improvement that the marketing team needed. Three outputs, three inconsistent documents, all written from memory instead of from the actual diff.

What You Get

• Change classification engine that analyzes git log and git diff output to classify every commit or diff hunk by type (Feature, Fix, Breaking, Performance, Refactor, Docs, Test, Chore) — with detection rules for BREAKING CHANGE markers, removed public APIs, new files adding functions, and test-only changes
• PR description template with Summary (one paragraph: what and why), Changes (grouped by type with file path context), Technical Details (scope, tests, dependencies), and Checklist — structured for scannability, not wall-of-text
• Release notes generation following GitHub Release conventions with New Features (with usage context), Bug Fixes (what was broken and how it's resolved), Breaking Changes (with migration guidance and before/after code examples), Performance Improvements (with metrics when available), and a compare link
• CHANGELOG.md entry following Keep a Changelog format (Added, Changed, Deprecated, Removed, Fixed, Security) with user-facing impact descriptions in imperative mood and issue/PR references
• Breaking change detection that flags signature changes (function parameter type changed, return type changed), removed features, and restructured public APIs — generating migration guidance with before/after code examples for each
• Semantic version recommendation — automatically recommends major (any breaking change), minor (any feature), or patch (fixes/docs/chores only) with reasoning, so the human makes the final call with full context

Why This Beats Prompting It Yourself

When you paste a git diff into an LLM and ask for release notes, it invents descriptions that don't match the actual changes. It doesn't know that a renamed parameter is a breaking change. It doesn't detect that removing a function signature means downstream callers will break. It doesn't group changes by user-facing impact vs. internal implementation detail. This skill classifies changes based on the actual diff data — not from your memory of what the PR was supposed to do — and produces output in the exact format required by your target (PR body, GitHub Release, CHANGELOG.md).

Example Session

You: "Generate release notes for v1.4.0..v1.5.0."

Agent output:

### New Features

- **GraphQL Subscriptions**: Real-time data streaming over WebSocket.
  Subscribe to any query and receive updates when underlying data changes.
  See the [subscription guide](docs/subscriptions.md) for setup. (#847)

- **Real-time Metrics Widget**: Dashboard component showing live request
  rates, error rates, and p99 latency. Auto-refreshes every 5 seconds. (#851)

### Bug Fixes

- **CORS Preflight for WebSocket**: Fixed WebSocket connections failing
  behind CORS proxies. The preflight handler now responds correctly to
  OPTIONS requests for the /ws endpoint. (#849)

### Performance Improvements

- **Query Result Caching**: 60-second cache layer for repeated SELECT
  queries. 3x improvement on dashboard queries under load. (#853)

**Recommendation:** Minor version bump (1.4.0 → 1.5.0) due to new features.
**Total commits:** 5 | Features: 2 | Fixes: 1 | Performance: 1 | Docs: 1

Use Cases

• Generating PR descriptions before opening a pull request
• Creating release notes for GitHub Releases after merging
• Maintaining a CHANGELOG.md in Keep a Changelog format across releases
• Producing per-package release notes in monorepo environments
• Generating audit trail changelogs from existing tag ranges for compliance

Known Limitations

The output quality depends on commit message quality — non-Conventional Commits are classified by diff analysis but with degraded accuracy. Monorepo single-output mode may miss per-package nuances; use scoped git log commands for package-specific notes. Breaking change detection is heuristic-based and may miss implicit breaks (behavioral changes without signature changes). Version recommendations are advisory — the human decides the final version based on factors the diff analysis cannot capture (product roadmap, marketing plans, partner agreements).