Run this skill after publishing a new version.

It will:

1. Find the last documented change in CHANGELOG.md (or the beginning of history if the file doesn't exist)
2. Diff from that point to HEAD
3. Draft categorized entries
4. Ask you to confirm anything ambiguous
5. Write/update CHANGELOG.md

Progress:

• Step 1: Locate or create CHANGELOG.md
• Step 2: Determine the diff range
• Step 3: Gather evidence (diff + commits + PR titles)
• Step 4: Categorize changes
• Step 5: Ask clarifying questions for anything uncertain
• Step 6: Draft the entry
• Step 7: Write to CHANGELOG.md

Step 1: Locate or create CHANGELOG.md

• If CHANGELOG.md exists, read it. The most recent version heading marks the last documented point.
• If it doesn't exist, create it with a # Changelog header and a note that it follows Keep a Changelog. Then generate an initial entry summarizing the current state of the project (from full git history or first commit to HEAD, whichever is feasible).

Step 2: Determine the diff range

• Find the git ref/tag/commit associated with the last changelog entry (look for a version tag matching the last heading, e.g. ## [1.2.0]).
• If no matching tag exists, use the date of the last entry to find the nearest commit, or ask the user which commit/tag to diff from.
• Diff range = last_ref..HEAD.

Step 3: Gather evidence

Collect, don't guess:

• git log last_ref..HEAD --oneline for commit messages
• git diff last_ref..HEAD for actual code changes
• PR titles/descriptions if available (via gh pr list --state merged or similar)
• The new version number (from package.json, pyproject.toml, a git tag, or ask the user)

Only claim a change happened if it's visible in the diff or explicitly confirmed by the user. A commit message alone ("fix bug") is not enough evidence — look at the actual diff to describe what was fixed.

Step 4: Categorize changes

Sort findings into Keep a Changelog categories:

• Added — new features
• Changed — changes to existing functionality
• Fixed — bug fixes
• Removed — removed features
• Security — vulnerability fixes
• Deprecated — soon-to-be removed features

Skip internal-only changes users don't care about: refactors with no behavior change, test additions, CI config, formatting, dependency bumps with no user impact. When unsure if something is user-facing, ask.

Step 5: Ask clarifying questions

Ask only when the diff is genuinely ambiguous — e.g.:

• A diff touches auth code but the intent (bug fix vs. new restriction) isn't clear
• Multiple unrelated changes are bundled and you need a one-line description of the "why"
• The version number isn't obvious

Batch questions together instead of asking one at a time. If the user doesn't answer or says "skip," omit that item rather than guessing.

Step 6: Draft the entry

Write in plain, user-facing language, not commit-speak. Translate:

• fix: null pointer in checkout flow → "Fixed an issue where checkout could fail unexpectedly"
• feat: add CSV export → "Added the ability to export data as CSV"

Use short bullets, bold the feature name when helpful, and keep one idea per bullet.

Step 7: Write to CHANGELOG.md

• Insert the new version section above the previous most-recent version, below the # Changelog header.
• Format:

Markdown
undefined

Example 1: Input: Diff shows a null check added in checkout.js around payment processing, commit message says "fix: handle null payment method". Output:

Markdown
### Fixed
- Fixed an issue where checkout could fail if a payment method wasn't fully loaded.

Example 2: Input: Diff adds a new exportToCsv() function and a new "Export" button in the UI; no commit message context. Output:

Markdown
### Added
- **CSV Export**: Added a new "Export" button to download your data as a CSV file.

(No clarifying question needed — the diff is self-explanatory.)

Example 3: Input: Diff modifies rate-limiting thresholds in auth/middleware.js with no clear commit message or PR description. Output: Ask the user: "I see the rate limit in auth/middleware.js changed from 100 to 50 requests/min. Was this a security fix, a bug fix, or a deliberate policy change? This affects how I categorize it."