v3.0.4 to v3.1.0

---

name: update_changelog

description: Create or update a day-grouped, add-only CHANGELOG.md from git commit history. Use when asked to generate, refresh, or maintain a repository changelog. Produces newest-first day sections while keeping existing entries immutable and processes one day at a time to stay within context limits.

author: Andreas F. Hoffmann

license: MIT

---

# update_changelog

<update_changelog_skill>

<objective>Create or update a `CHANGELOG.md` in the repository root: a human-readable, day-grouped, add-only history derived from git commits, newest day first. Record later committed changes as new entries or day sections while preserving existing entries as immutable historical facts.</objective>

<command_intent>build CHANGELOG.md, refresh changelog from git history, add the missing days to the changelog</command_intent>

<tools>

<prepare_changelog_day>Run `scripts/prepare_changelog_day.sh YYYY-MM-DD` from this skill when it is available. The script writes one structured context blob for a single calendar day to a file under the system tmp dir, with the day's commit subjects and bodies, the deduplicated repo-relative file list, per-file net diffs for the day, and generic placeholders for binary files. Its stdout prints exactly two lines: the context file's absolute path, then a one-line consumption directive. Exits 1 with `no commits on <date>` when the date has no commits — skip silently.</prepare_changelog_day>

</tools>

<consume_context>

<full_read>Use the `Read` tool on the path printed by `scripts/prepare_changelog_day.sh` and read the entire file. This is the default path and works for normal-sized days.</full_read>

<paginated_read>If the file overflows `Read`'s default window, call `Read` again with `offset`/`limit` and continue in sequence until every byte is covered. Consume each page in order.</paginated_read>

<ordered_slicing_fallback>Only when the file is so large that paginated `Read` is impractical, use `grep`/`awk`/`sed` via Bash to split the file into ordered slices. Read those slices sequentially from the top of the file through the end, preserving the original order of `<commit>` and `<file_change>` sections.</ordered_slicing_fallback>

<hard_rules>Use the script's context file as the sole per-day source. Never re-derive the day with `git log`, `git diff`, or `git status`; never truncate the blob with `head`; never sample by filename. Iterate every `<commit>` and `<file_change>` section in order before composing the day section.</hard_rules>

</consume_context>

<output_contract>

<header>The file always begins with the H1 `# CHANGELOG — {Project Name}`, then a blank line, then the line stating that entries are grouped strictly by day, kept on their original implementation dates, and immutable once written. Substitute `{Project Name}` from the repo directory name, `package.json`, `Cargo.toml`, or the README's H1.</header>

<day_section>One `## YYYY-MM-DD — {Day theme}` heading per calendar day that has commits, ordered newest-first. `{Day theme}` is a 2-5 word editorial summary of that day's dominant focus. End every day section with a horizontal rule (`---`).</day_section>

<entry_line>One bullet per logical change inside the day section in the format `- **Category:** Plain-English summary of the change.`.</entry_line>

<categories>`added` for new features or capabilities. `changed` for behavior that differs from before. `deprecated` for retired or removed behavior, or behavior kept only for legacy use. `refactored` for the same output from the same input with faster, more robust, or less buggy internals. `docs` for documentation- or specification-only changes. Express replacement or removal as a `deprecated` or `changed` entry on the date that later work happened.</categories>

<files_changed_line>End every day section with a files-changed bullet listing every path the day touched, repo-relative, backtick-wrapped, comma-separated, deduplicated. Shape: a `- **Files changed:**` prefix followed by each path wrapped in single backticks and separated by a comma plus a space.</files_changed_line>

<insertion_anchor>The header block — the H1 plus the immutability/grouping line beneath it — ends at a stable boundary, and the first `## YYYY-MM-DD` heading is the top of the day list. That boundary is the one anchor for every day-section insertion. Invariant: a new day section always lands in the seam immediately between the end of the header block and the current first `## YYYY-MM-DD` heading — never inside the header block, never below an existing day section. The invariant governs **new** day sections only; when a run reopens the most recent recorded day, that day's existing section is extended in place per `<last_recorded_day_reconciliation>`, not re-inserted.</insertion_anchor>

</output_contract>

<policy>

<run_scope>Build each run from committed git history only; ignore uncommitted and untracked working-tree state. On incremental runs, treat the most recent recorded day as provisionally complete because commits can share that calendar day after its section was first written. Reopen that day and every later committed date; days older than the most recent recorded day are settled for that run.</run_scope>

<context_safety>Two things are released incrementally, on different schedules — keep them distinct. The large per-day context blob from `<consume_context>` is what can overflow the context window on a long history, so consume and release it one day at a time on **both** paths, incremental and cold build alike. Flushing each composed day section to `CHANGELOG.md` before the next is the separate cold-build rule: a cold build walks the full history, so it writes each completed day section to disk and lets it fall out of working context before composing the next, keeping only one day's material live at a time. An incremental run touches only a few new days, so it composes their small sections together and lands them in one insert per `<newest_first>` with no per-day section flush. Only the composed-section batch size differs between the two paths; the one-day-at-a-time discipline for the context blob is identical on both.</context_safety>

<newest_first>Maintain strict newest-first day ordering, and land every new day section against the single anchor defined in `<insertion_anchor>`: the seam between the header block and the current first `## YYYY-MM-DD` heading. Locate that seam with a bounded read of only the header block plus the first existing `##` heading — never a whole-file read. One anchor, two insertion shapes:

<incremental_prepend>Incremental run (a few new days — the common case): compose all the run's new day sections into one block already ordered newest-first, then perform a single insert that splices that block into the seam, anchoring the edit on the first existing day heading. One edit, one seam, nothing below it reordered.</incremental_prepend>

<cold_build_insert>Cold build (no `CHANGELOG.md`, long history): under `<context_safety>`, insert each completed day section into the same seam immediately below the header block as it is composed. Processing oldest→newest with every day inserted at the top yields a newest-first file without holding the whole history in context.</cold_build_insert>

When a run reopens the most recent recorded day, extend that day's existing section in place per `<last_recorded_day_reconciliation>` rather than inserting a new section.</newest_first>

<one_entry_per_logical_change>Squash related commits into a single bullet. Write one entry per logical change, not per commit.</one_entry_per_logical_change>

<date_immutability>Keep entries on their original implementation date forever. Treat each existing entry's date, text, and category as frozen once written. Record later committed changes only as new entries on the dates those changes happened.</date_immutability>

<summary_style>Write summaries in plain English, past tense, describing what was done. Leave why and how out of the summary. Stay concise but specific enough that a reader unfamiliar with the codebase understands the scope.</summary_style>

<preserve_existing>Preserve existing day sections and entries in place. Add new day sections or entries for later committed changes while keeping existing entry dates, text, and categories unchanged. For the reopened most recent recorded day, follow `<last_recorded_day_reconciliation>` instead of regenerating the section.</preserve_existing>

<last_recorded_day_reconciliation>When an incremental run reprocesses the most recent recorded day, compare that day's committed history with the existing section. Keep every existing entry's date, category, and text unchanged; add entries for newly found logical changes, extend the `- **Files changed:**` line with missing paths, and revise the day theme only when the added commits change the day's dominant focus.</last_recorded_day_reconciliation>

<model_authority>The model owns summarization, day-theme composition, and category assignment. Use script output as evidence and execution support.</model_authority>

<workflow_authority>Treat this skill as the source of truth for `/update_changelog` workflow, output format, and entry style.</workflow_authority>

</policy>

<procedure>

<resolve_project_name>Resolve `{Project Name}` from the repository directory name, an existing project title in the README's H1, the `name` field of `package.json` or `Cargo.toml`, or another canonical project metadata file.</resolve_project_name>

<enumerate_dates>Build the date list from committed history. When `CHANGELOG.md` does not exist, run `git log --reverse --format='%ad' --date=short --no-merges | sort -u` to list every distinct commit date in the repository, oldest-first. When updating an existing changelog, read from the top only until the first `## YYYY-MM-DD` heading; because the changelog is newest-first, that heading is the most recent recorded day `D`. Then run `git log --reverse --format='%ad' --date=short --no-merges --since={D}T00:00:00 | sort -u` (or an equivalent committed-history query) to list `D` and every later distinct commit date. Keep `D` in the list because same-day commits can land after its section was written.</enumerate_dates>

<ensure_header>If `CHANGELOG.md` does not exist, create it with the header block. If it exists, leave the header in place.</ensure_header>

<day_loop>

For each selected date, oldest-first:

<substeps>

<substep>Run `scripts/prepare_changelog_day.sh YYYY-MM-DD` to produce that day's context file path. If the script exits 1, skip the date silently.</substep>

<substep>Read the returned context file according to `<consume_context>`, covering the full file before composing the day section.</substep>

<substep>Read every `<commit>` and `<file_change>` block from the consumed context. Aggregate related changes into logical entries, choose categories, and compose a 2-5 word day theme.</substep>

<substep>Build the day section from the day theme, the entry bullets, and the `- **Files changed:** ...` bullet using the paths from `<files_changed>`. End the section with `---`.</substep>

<substep>Place the composed section by run type, per `<newest_first>` and `<context_safety>`. On a cold build, insert this day's section into the seam immediately below the header block now, then flush to disk before composing the next day so prior detail falls out of working context. On an incremental run, add this day's section to the top of the run's accumulating newest-first block and hold it — the single splice happens in `<land_new_days>`. For the reopened most recent recorded day, reconcile its existing section in place per `<last_recorded_day_reconciliation>` instead of inserting a new one.</substep>

</substeps>

</day_loop>

<land_new_days>On an incremental run, after the loop has composed every selected day, perform the one anchored prepend: splice the accumulated newest-first block into the seam between the header block and the first existing day heading, per `<newest_first>`. On a cold build, each day section was already inserted during the loop, so no separate splice runs here.</land_new_days>

</procedure>

</update_changelog_skill>