changelog

name	changelog
description	Use when writing or updating a changelog. Always load this skill before editing the changelog file. Triggers on "update the changelog", "add a changelog entry", "changelog", or editing CHANGELOG.md.

Changelog

A changelog is for an external user to glance over and understand what changed for them, without reading the code or the commits.

It is not a record of internal work. Refactors, renamed modules, reworked algorithms, and implementation details do not belong here unless the user can observe the difference.

Writing an Entry

Write from the user's perspective: what they will now see or get. Not from the developer's perspective: what we did to the code.

• One bullet per change. Terse, present tense, a finished thought.
• Plain language. No module names, function names, or "reorganized the X".
• Describe the observable change or the benefit, not the mechanics.
• If a change is purely internal with no user-visible effect, it likely does not need an entry at all.

Good vs Bad

A Rust diff tool reworked the algorithm that aligns lines. The user-visible result is cleaner diffs with fewer spurious changes.

Bad (describes internal work):

Changed: reworked the line-alignment algorithm to use a Myers-based LCS pass before the token diff, replacing the old greedy matcher.

Good (describes what the user sees):

diff: align changed lines more accurately, reducing noisy diffs on edits.

Merging Unreleased Entries

Within the [Unreleased] section, related entries can be merged to simplify the changelog. When several unreleased bullets describe the same user-facing improvement, collapse them into a single bullet framed from the user's perspective. This applies even when the bullets span different groups (Added / Changed / Fixed). It keeps the unreleased section concise before a release is cut.

This only applies to unreleased entries. Do not merge or edit entries in already-released sections.

Format (Keep a Changelog)

Entries go under an [Unreleased] section, grouped by Added / Changed / Fixed.

Optionally prefix a bullet with the surface area, matching the repo's existing style (e.g. diff:, traces TUI:).

## [Unreleased]

### Added
- traces TUI: filter spans by service name.

### Changed
- diff: align changed lines more accurately, reducing noisy diffs on edits.

### Fixed
- crash when opening an empty file.