§ reference · skill

changelog

Regenerates the `[Unreleased]` section of every affected `CHANGELOG.md` from commits + uncommitted hunks, classified by Conventional Commit prefix. Monorepo-aware, idempotent.

arguments --since <ref>

§ 01 · purpose

Purpose

Keeps [Unreleased] blocks honest as work lands. changelog reads everything since the last release tag — committed and uncommitted — classifies by Conventional Commit prefix, and rewrites each affected CHANGELOG.md. Safe to re-run; results converge.

§ 02 · when to use

When to use it

Preparing a release and the [Unreleased] block is out of date.
You want a draft for review before a release script runs.
Skip when no CHANGELOG.md exists or no release tag has ever been cut.

§ 03 · inputs

Inputs

Name	Required	Source
$ARGUMENTS (`--since <ref>`)	no	Range hint — defaults to `git describe --tags --abbrev=0`

§ 04 · outputs

Outputs

Artifact	Path	Format
Rewritten `[Unreleased]` block per affected `CHANGELOG.md`	every tracked `CHANGELOG.md`	Keep a Changelog 1.1.0

§ 05 · key steps

Key steps

Bail-out checks Why: Verifies git, at least one CHANGELOG.md, and at least one release tag. Stopping early on missing prerequisites prevents silent no-op runs.
Resolve scope per CHANGELOG Why: Nested CHANGELOGs own their parent directory; root CHANGELOG owns the repo *minus* nested-CHANGELOG directories. Path-scoped git log keeps monorepo entries from bleeding across packages.
Collect committed + uncommitted hunks together Why: A virtual "pending" change set is added alongside committed history so drafts reflect what's actually changing — not just what's already in git log.
Classify per Conventional Commit mapping Why: feat:→Added, fix:→Fixed, perf:→Performance, etc. Skips release-pipeline housekeeping and test-only commits so entries are user-visible.
Flag breaking changes Why: ! suffix, BREAKING CHANGE: footer, or removed/renamed exports trigger an additional entry under Breaking / Upgrade Notes — a one-line upgrade instruction the release notes can reuse.
Preview and confirm before applying Why: Diff is shown first so the developer can correct misclassifications cheaply. Apply step uses Edit so other sections of the file are never touched.

§ 06 · related skills

upstream commit implement