Prepare Release Changelog

Prepare Release Changelog

Build a complete, evidence-backed release ledger before writing release notes. Treat missing or unresolved commits as release blockers; do not infer coverage from PR titles or the existing changelog alone.

1. Establish the exact release range

1. Read CONTRIBUTING.md, AGENTS.md, and the top and link-list portions of CHANGELOG.md.
2. Require the exact target version before editing. Do not use [Unreleased] as a substitute when the version is unknown.
3. Record the checkout, branch, HEAD, worktree status, remotes, and divergence from origin/main. Preserve unrelated or pre-existing changes.
4. Refresh live state with git fetch --prune origin main --tags and identify the latest published, non-draft, non-prerelease GitHub release with gh release list / gh release view. Do not substitute the numerically highest local tag without checking GitHub. If preparing a prerelease line, require the user to name its base release explicitly.
5. Resolve the release tag and candidate head to full SHAs. Default the candidate to refreshed origin/main; if the user names a SHA/ref, use that exact head. Report local commits ahead of origin/main separately and do not include them without explicit direction.
6. Require the release tag to be an ancestor of the candidate head. Stop if the tag, candidate, repository identity, or GitHub release cannot be verified.

Do not edit CHANGELOG.md during this discovery phase.

2. Build and validate the coverage ledger

Run the bundled inventory script from the repository root:

python3 .claude/skills/prepare-release-changelog/scripts/release_inventory.py \
  --from-tag <published-tag> \
  --head <candidate-sha> \
  --repo illegalstudio/elephc \
  --format json

The script walks the first-parent history, recognizes GitHub merge and squash commits, queries associated PRs for ambiguous commits, expands every merge's introduced commits, and reconciles the result against the complete Git commit range.

Require all of these before drafting:

• unaccounted_commits is empty;
• errors is empty;
• every first-parent integration is a verified merged PR or a verified direct commit;
• every PR targets main, is merged, and has a merge commit reachable from the candidate;
• the reported base and candidate SHAs match the refs selected above.

Never silently classify a commit as direct when GitHub association lookup failed. Investigate unresolved or ambiguous rows and rerun the inventory until coverage is complete.

3. Inspect what actually shipped

For every PR and direct commit in the ledger:

1. Inspect its metadata, changed paths, diff, tests, documentation, linked issues, and relevant source. Titles and bodies are orientation, not semantic proof.
2. Describe the shipped user-visible behavior, compatibility change, performance effect, security impact, or developer-facing interface change.
3. Mark internal chores, repository statistics, generated data, tests-only changes, and refactors with no observable effect as omit, with a concise reason.
4. Detect follow-ups, partial fixes, reverts, and several PRs implementing one coherent outcome. Consolidate only when the combined wording remains accurate; retain every source PR/commit in the ledger.
5. Compare every candidate semantically with the target version section, if it already exists. Mark existing coverage, duplicates, stale bullets, and claims not supported by the audited range. [Unreleased] should remain empty and is not the source of release coverage.

Every ledger row must end as include, covered, omit, reverted, or needs decision. No source may disappear merely because it does not deserve its own bullet.