/gaia-changelog

user-facing
Category:
Deployment
Lifecycle phase:
5 -- Deployment
Arguments:
[version]

What it does

/gaia-changelog generates a changelog entry from git history. It gathers commits since the last release tag, groups them by Keep a Changelog category (Added, Changed, Fixed, Deprecated, Removed, Security), cross-references story keys back to story files, and writes or appends to CHANGELOG.md.

When to use it

  • You are preparing a release and need a changelog entry.
  • You want to document what changed since the last tagged version.

Prerequisites

  • Git history must be available. The command reads commits since the last release tag.

How to invoke

/gaia-changelog
/gaia-changelog 1.3.0

What it does step by step

  1. Gather sources Reads git commits since the last release tag. If no tags exist, reads the entire history.
  2. Validate version If a version argument is provided, validates it as a valid semver string or the literal "Unreleased".
  3. Categorize changes Groups each commit into Added (feat:), Changed (refactor:, chore:), Fixed (fix:), Deprecated, Removed (BREAKING CHANGE), or Security. Commits without a conventional-commit prefix go into an Uncategorized group.
  4. Format entry Renders the entry in Keep a Changelog format with story-key cross-references linking back to story files.
  5. Write to CHANGELOG.md Appends the new entry to the repository root CHANGELOG.md, inserting it above the previous top entry.

Inputs

InputSourceDescription
versionCommand argument (optional)The version number (semver) or "Unreleased". Defaults to Unreleased if omitted.

Outputs

OutputLocationDescription
Changelog entryCHANGELOG.mdNew entry appended to the changelog file.

Example session

> /gaia-changelog 1.3.0

Gathering commits since v1.2.0...
  42 commits found, 3 merges excluded.

## [1.3.0] -- 2026-05-07

### Added
- User authentication with email/password -- E3-S7
- Token refresh endpoint -- E3-S8

### Fixed
- Login redirect on expired session -- E3-S9

Written to CHANGELOG.md

What to run next

  • /gaia-release -- uses the changelog entry in the GitHub Release notes.

Troubleshooting

No commits since last tag

The changelog entry will show a note that no changes occurred since the previous version.

Expected semver or Unreleased

The version argument must be a valid semver string (e.g., 1.3.0) or the literal "Unreleased".