grimoire-changelog

name	grimoire-changelog
description	Generate a structured CHANGELOG from git history and session chain. Use when: changelog, release notes, what changed, version bump, prepare release, summarize changes, diff since last release, release prep. Combines git log analysis with session chain context for rich changelogs.

Grimoire Changelog

Generate a structured CHANGELOG entry from git commits and session chain context.

When to Use

• Preparing a release or version bump
• When the user asks "what changed?", "generate changelog", or "release notes"
• Before tagging a new version
• Periodic summary of recent work

Procedure

Step 1 — Identify Scope

Determine the range of changes to cover:

git tag --sort=-version:refname | head -5

If tags exist, use the last tag as baseline. Otherwise, use a date or commit range.

git log --oneline <last-tag>..HEAD

Or by date:

git log --oneline --since="2 weeks ago"

Step 2 — Categorize Commits

git log --pretty=format:"%h %s" <range> | sort -t: -k1

Group by conventional commit prefix:

• feat: — New features
• fix: — Bug fixes
• docs: — Documentation
• refactor: — Code restructuring
• test: — Test additions/changes
• chore: — Maintenance, dependencies

Step 3 — Enrich with Session Chain

cat _grimoire-runtime/_memory/session-chain.jsonl 2>/dev/null | tail -10

Cross-reference session summaries with commits to add context:

• What was the intent behind each change?
• What decisions drove the implementation?
• Any notable trade-offs or design choices?

Step 4 — Check File Impact

git diff --stat <range>

Quantify the changes:

• Files changed
• Lines added/removed
• Key files affected

Step 5 — Read Current CHANGELOG

head -30 CHANGELOG.md 2>/dev/null

Understand the existing format and continue with the same style.

Step 6 — Generate Entry

Format following Keep a Changelog convention:

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

### Added
- Feature description (#commit-ref)

### Changed
- Change description

### Fixed
- Bug fix description

### Stats
- N files changed, +N insertions, -N deletions
- N commits by N contributors

Step 7 — Update CHANGELOG.md

Prepend the new entry at the top of CHANGELOG.md (after the header), preserving all existing entries.

Step 8 — Suggest Version Bump

Based on changes:

• PATCH (X.Y.Z+1) — only fixes and minor changes
• MINOR (X.Y+1.0) — new features, backward compatible
• MAJOR (X+1.0.0) — breaking changes

Check current version:

cat version.txt 2>/dev/null

Quick Mode

For a rapid summary without full formatting:

git log --oneline --since="1 week ago" | head -20

Present as a bullet list without full CHANGELOG structure.

Notes

• Always preserve existing CHANGELOG entries — prepend, never overwrite
• Use commit hashes as references for traceability
• Session chain provides the "why" behind the "what" from git
• If no conventional commit prefixes are used, categorize by file path patterns