Changelog Maintenance

Core Question

How should the changelog be updated to reflect observed changes in the project’s existing format without inventing unsupported release information?

When To Use

Use this skill when the user asks to:

• add or update CHANGELOG.md entries,
• maintain an Unreleased section,
• promote Unreleased to a version section,
• validate changelog completeness,
• categorize changes as added, changed, fixed, deprecated, removed, security, or breaking.

When Not To Use

Do not use this skill to draft polished release announcements, decide or edit versions, create tags, publish releases, push files, or create commits.

Route to:

• release-notes for user-facing release-note prose.
• version-bump for version decisions or version file edits.
• tag-release for Git tag creation.
• a future publish-release skill or manual workflow for publication.
• atomic-commits or conventional-commits for commit workflows.

Required Evidence

Inspect or establish:

• existing changelog file and style,
• project changelog conventions in README/CONTRIBUTING/release docs,
• commit, PR, or issue evidence for requested range,
• current version from version files when promoting a release section,
• release date only when provided or evidenced,
• breaking changes, migrations, deprecations, security claims, and performance claims only when evidenced,
• duplicate entries already present.

Operating Contract

You MAY:

• inspect changelog and release evidence,
• add or edit changelog entries in existing style,
• promote an unreleased section to a version when version/date evidence exists,
• deduplicate entries conservatively,
• create a changelog only when explicitly requested.

You MUST:

• preserve existing changelog format,
• keep changes scoped to the changelog unless explicitly routed,
• make breaking changes and migration notes visible when evidenced,
• state evidence gaps,
• avoid unsupported claims,
• inspect diff after mutation.

You MUST NOT:

• invent release dates, PR numbers, issue IDs, performance claims, security claims, migration impact, or compatibility impact,
• delete historical entries or rewrite old releases without explicit confirmation,
• change the global changelog format without explicit confirmation,
• tag, publish, push, or change version files from this skill.

State / Risk Table

Workflow

1. Identify whether task is draft, update, validation, creation, or promotion.
2. Inspect changelog format and project conventions.
3. Inspect commit/range/PR/version/date evidence as needed.
4. Classify risk and missing evidence.
5. Update or draft entries using existing style.
6. Avoid unsupported claims and duplicates.
7. Inspect diff when mutating.
8. Report entries changed, evidence, verification, and limitations.

Decision Rules

• Preserve existing format; do not migrate the whole changelog unless requested and confirmed.
• Keep Unreleased semantics if the project already uses them.
• Do not invent release dates, PR numbers, issue IDs, security claims, performance claims, migration impact, or compatibility impact.
• If commit range evidence is missing, produce a limited draft and state the evidence gap.
• Internal-only changes may be omitted or grouped according to existing style.
• Breaking changes must be visible and not buried in generic categories.
• Version changes are owned by version-bump.
• Git tags are owned by tag-release.
• Publication is out of scope.

Tool Rules

Allowed:

• read changelog and release evidence,
• edit changelog when explicitly requested,
• inspect diffs after mutation.

Requires explicit confirmation:

• changelog creation,
• deleting historical entries,
• rewriting old releases,
• changing global changelog format.

Forbidden in this skill:

• tag creation,
• release or package publication,
• pushing files,
• version-file mutation,
• commit creation.

Verification

Minimum verification:

• R1: self-check draft against evidence.
• R2: inspect changelog diff and section placement.
• R3: inspect old-release/global-format diff and report residual risk.

Verify:

• entries match existing format,
• duplicate entries are not introduced,
• unsupported claims are absent,
• breaking/migration information is visible when evidenced,
• version/date headings are supported.

Output Contract

Final response should include:

## Result

- Changelog entries drafted or changed.

## Evidence

- Changelog format, range, commits, PRs/issues, version/date used.

## Verification

- Diff/section review and unsupported-claim check.

## Limitations

- Missing range, missing date, or out-of-scope release actions.

Stop / Confirmation Rules

Stop when changelog format, release range, version/date evidence, or requested rewrite scope is ambiguous in a way that could misrepresent the release.

Requires confirmation for:

• creating a new changelog file,
• deleting historical entries,
• rewriting old releases,
• changing global changelog format.

Route tag, publish, push, version edits, and commit execution to owning skills.

Lazy-load References

Load:

• references/formats.md when changelog style is unclear.
• references/category-mapping.md when category selection is ambiguous.
• references/examples.md when the user asks for examples.
• references/failure-modes.md for duplicate or unsupported-claim risks.
• references/verification.md for changelog diff checks.