tomevault-io Generate Release Changelog
Produce a tight, human-readable changelog for the latest published Git tag and print it as the final assistant message. This skill is read-only — do not write, edit, or create any files, directories, or git/GitHub objects at any point.
The product owner reads this to understand what changed for users, not what was implemented. Optimize for impact density: every bullet must answer "what is different now from a user's seat?". Cut anything that does not.
Hard constraints (non-negotiable)
- No file writes: do not use Write, Edit, Bash mkdir/touch, or any equivalent.
- No remote writes: do not run git commit, git tag, git push, or gh release create/edit.
- Output is a single chat message in Markdown. No preamble ("Here's your changelog:"), no follow-up questions, no commentary after the changelog ends.
- If the commit range is empty, print a single line:
No commits found between <previous> and <latest>.and stop.
Step 1 — Resolve the tag range
Run in parallel:
git tag --sort=-creatordate | head -5
git describe --tags --abbrev=0
latest= output ofgit describe --tags --abbrev=0.previous= the next tag in the sorted list. If no previous tag exists, usegit rev-list --max-parents=0 HEAD | head -1and note "initial release" in the changelog.- If the user provides a tag argument, treat that as
latest; derivepreviousfrom the sorted list.
Step 2 — Collect commits
git log <previous>..<latest> --no-merges --pretty=format:'%H%x09%s%x09%an'
For each commit, capture changed files:
git show --stat --pretty=format:'' <sha> | head -40
For commits with ambiguous subjects (e.g., chore: misc, wip, update), inspect the diff only for paths that look load-bearing — skip obvious docs: / chore: commits:
git show <sha> -- <relevant-paths>
Step 3 — Classify commits
Map every commit to exactly one bucket. Conventional Commit prefixes are a hint; the diff is authoritative — a chore: commit that ships user-visible behavior belongs in Features.
Buckets (use this order in the output):
- Breaking changes — backward-incompatible changes to config schema, flags, output format, file layout, or API contracts.
- Features — new user-visible capability.
- Improvements — enhancements to existing behavior (UX, performance, validation, compatibility).
- Fixes — corrections to incorrect behavior.
Drop everything else. Do not include sections for documentation, refactors, tests, CI, dependency bumps, or internal cleanup. The only exception: if a commit changes something downstream users will feel — minimum Go version bump, removed dependency, security CVE — surface it under Breaking changes or Improvements with a product-facing sentence.
Skip purely cosmetic commits (whitespace, typo).
Merge near-duplicates into one bullet. Two commits that fix the same bug get one line. Three commits that build one feature get one line.
Step 4 — Write each bullet
Strict rules — apply to every bullet:
- One sentence. Maximum 15 words. Aim for 8–12.
- Lead with the user-visible state, not the work performed. Describe the new behavior as it now is.
- Name the concrete surface (flag, command, config field, file) only when it is the thing the user touches. Drop it if the impact is clearer without it.
- No filler: cut "now", "you can now", "users can", "we have", "this release", "added support for", "improved the way", "made it possible to".
- No commit-message echoes. Rewrite for a reader who has not seen the code.
- Active voice. Present tense.
- No commit SHAs, no author names, no PR/issue numbers unless they carry meaning the reader needs.
Examples (calibrate against these):
| Avoid | Prefer |
|---|---|
feat: improve working with cwd |
Commands run from any subdirectory inside the repo. |
Added support for storing local document relations in .sync-state.json so they survive across sync runs. |
Local relations persist across syncs. |
Fixed a bug where the init command would fail if the .archcore directory already existed with a partial config. |
``init no longer fails on partial existing configs. |
Improved the validation logic for sync mode fields to provide clearer error messages. |
Sync-mode validation errors point at the offending field. |
BREAKING: The project field has been removed from the configuration schema. |
``projectfield removed fromsettings.json. |
If you cannot write a bullet that meets these rules, the change probably does not belong in the changelog — drop it.
Step 5 — Output format
Emit exactly this structure (omit any section that would be empty):
# <latest-tag>
_<YYYY-MM-DD> · <N> commits_
<One sentence, max 20 words. The headline of the release in user-impact terms. Omit the line entirely if no single change dominates — do not pad.>
## Breaking changes
- ...
## Features
- ...
## Improvements
- ...
## Fixes
- ...
---
`<previous-tag>...<latest-tag>`
- Release date:
git log -1 --format=%ai <latest-tag>(date portion only). - Do not invent items not backed by a commit in the range.
- The headline is optional. Skip it rather than write a generic one ("This release brings improvements and fixes.").
- A release with three good bullets is better than one with twelve mediocre ones.
Source: archcore-ai/cli — distributed by TomeVault.