docs: terser CHANGELOG entries, add changelog skill

The 5 entries I added for the FSST/dispatch work were verbose
paragraphs (full rationale + before/after numbers inline) — too
verbose per feedback. Rewrote them as one-sentence titles ending in
a commit link; the numbers and rationale live in the commit message,
which the link points to.

Also records a standalone `changelog` skill (.claude/skills/) codifying
this convention, split out of the `release` skill's CHANGELOG-sync step
so it can run without cutting a release.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dfa1

.claude/skills/changelog.md

@@ -0,0 +1,64 @@
+---
+name: changelog
+description: Write CHANGELOG.md entries for unreleased commits — terse, one-line bullets that link to the introducing commit(s), not paragraphs. Triggers on "prepare the changelog", "update CHANGELOG", "write changelog entries", or invokes `/changelog`. Standalone version of the `release` skill's "CHANGELOG sync" step — use this when you want entries written without cutting a release yet.
+---
+
+## Overview
+
+Write CHANGELOG.md entries for commits that don't have one yet, under `## [Unreleased]`.
+Entries are **terse** — a title, not a paragraph — ending in a link to the introducing
+commit(s). The link is the receipt; anyone who wants the "why" and the numbers reads the
+commit message (`git show <sha>` or the GitHub commit page), not the changelog.
+
+## Steps
+
+1. Find the range of commits missing a changelog entry: compare `## [Unreleased]` in
+   `CHANGELOG.md` against `git log --oneline <last-documented-commit>..HEAD`. If unclear
+   where the last-documented commit is, ask.
+2. For each notable commit, write **one bullet**:
+   - A single short sentence — what changed, fewest words that stay precise. No numbers,
+     no "why", no before/after prose — those live in the commit message.
+   - End with the commit SHA(s), GitHub-auto-linked:
+     `([abc1234](https://github.com/dfa1/vortex-java/commit/abc1234))`
+   - One logical change spanning multiple commits: comma-separate SHAs, newest first.
+3. Categorize under the right `###` heading (create if missing): `Added` / `Changed` /
+   `Fixed` / `Performance` / `Removed` / `Security` — Keep-a-Changelog order (Added,
+   Changed, Deprecated, Removed, Fixed, Security), plus this project's `Performance`.
+4. Skip pure-internal churn: CI/Sonar fixes, source-tree moves, dedup refactors,
+   test/tooling-only commits (see [[feedback_changelog_terse]]) — omit rather than write a
+   bullet nobody user-facing cares about.
+5. Commit as `docs: CHANGELOG entries for <short description>`.
+
+## Example
+
+Good (terse — what to write):
+```
+- Utf8/Binary now use cost-based encoding selection instead of first-match dispatch. ([1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
+- FsstEncodingDecoder no longer throws on valid files with empty FSST metadata. ([1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
+```
+
+Bad (too verbose — do NOT write this):
+```
+- `CascadingCompressor` now runs `Utf8`/`Binary` columns through the same sample-and-measure
+  encoding competition `Primitive` columns already get, instead of first-match dispatch.
+  `DictEncodingEncoder` is registered ahead of `FsstEncodingEncoder`, so Dict always won
+  regardless of actual output size — confirmed by inspecting a 50k-row, high-cardinality
+  string file and finding `vortex.dict` where `vortex.fsst` is ~40% smaller. On
+  `highCardinalityUtf8_javaVsJni` (50k distinct 6-byte strings) this drops the Java/JNI
+  file-size ratio from 2.26× to 1.36× (801,908 → 483,336 bytes). ([1bbc3549](...))
+```
+The numbers and rationale belong in the commit message, not duplicated in the changelog.
+
+## Rules
+
+- Never invent entries for commits that don't exist — the link is the receipt.
+- Never leave a bullet without a commit link.
+- One sentence per bullet. If it needs two sentences, split it into two bullets, or the
+  extra detail belongs in the commit message instead.
+- Skip internal-only commits (matches the `release` skill's CHANGELOG sync policy).
+
+## When NOT to use
+
+- Finalizing a release's version header/date, or the compare link at the bottom of the
+  file — that's the `release` skill's job (its CHANGELOG sync step supersedes this one).
+- Writing release notes for work that isn't committed yet.

CHANGELOG.md

@@ -14,14 +14,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `MaskedEncodingEncoder` also tries `vortex.sparse` for a mixed-validity bitmap (fill = the majority value, patches = the minority positions) and keeps it over the raw bitmap when smaller — the patch-index array is compressed through a dedicated `vortex.sequence`/`fastlanes.delta`/FoR/bitpack cascade, so a clustered or regular null pattern (e.g. one null every 10 rows) collapses to a handful of bytes instead of a full bitmap. On the 200k-row, 10-chunk nullable low-cardinality Utf8 benchmark this drops the file a further 20% (107 KB → 86 KB) and the gap to the Rust reference from ~1.45× to ~1.17×. Also: `SequenceEncodingEncoder.encodeCascade` no longer lets `encode`'s "not an arithmetic sequence" exception escape when a stratified sample looked arithmetic but the full data wasn't — it now reports the cascade step as not applicable, like every other encoder's contract requires. (internal)
 - `ConstantEncodingEncoder` now accepts `DType.Bool` (previously `DType.Primitive` only), so any all-true or all-false dense Bool column — not just a masked/nullable one — can win `vortex.constant` through the normal per-column cascade, not only through `MaskedEncodingEncoder`'s dedicated check. `MaskedEncodingEncoder`'s validity encoding now delegates to it instead of duplicating the scalar-building logic. `RunEndEncodingEncoder` also gains a `vortex.runend` path for Bool: `MaskedEncodingEncoder` tries it alongside `vortex.sparse` and keeps whichever is smallest — `vortex.runend` wins on long clustered runs of valid/invalid rows (regardless of which value dominates), a shape `vortex.sparse`'s per-flip patch cost handles poorly. (internal)
 - `RleEncodingEncoder`/`RleEncodingDecoder` (`fastlanes.rle`) round out Bool coverage: the same FastLanes 1024-row chunked layout the numeric path uses, with a `vortex.bool`-encoded values pool (at most 2 distinct values per chunk) instead of a ptype-width one. `MaskedEncodingEncoder` tries it alongside `vortex.sparse`/`vortex.runend` and keeps the smallest — `DType.Bool` now has every general-purpose encoding family (`vortex.constant`, `vortex.sparse`, `vortex.runend`, `fastlanes.rle`) that `DType.Primitive` has. (internal)
-- `CascadingCompressor` now runs `Utf8`/`Binary` columns through the same sample-and-measure encoding competition `Primitive` columns already get, instead of first-match dispatch. `DictEncodingEncoder` is registered ahead of `FsstEncodingEncoder`, so Dict always won regardless of actual output size — confirmed by inspecting a 50k-row, high-cardinality string file and finding `vortex.dict` where `vortex.fsst` is ~40% smaller. On `highCardinalityUtf8_javaVsJni` (50k distinct 6-byte strings) this drops the Java/JNI file-size ratio from 2.26× to 1.36× (801,908 → 483,336 bytes). ([1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
-- `FsstEncodingDecoder` no longer throws on a valid file whose `vortex.fsst` metadata segment is absent. Proto3 omits fields at their default (zero/`U8`) value, so an all-`U8` metadata message legitimately encodes to zero bytes and the writer omits the segment entirely; the decoder previously treated any absent metadata as corruption. Also adds explicit buffer-count (3) and child-count (≥2) bounds checks, which the removed null-metadata check had been incidentally — and incorrectly — covering for a separate malformed-input case. ([1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
-- `FsstEncodingEncoder` now writes its symbol table in the order the Rust reference requires (`FSSTData::validate_symbol_lengths`: multi-byte symbols non-decreasing by length, then all length-1 symbols) — a Java-written file with an out-of-order table previously failed to open in the JNI/Rust reader. ([95e0dfb4](https://github.com/dfa1/vortex-java/commit/95e0dfb4))
+- `Utf8`/`Binary` columns now use cost-based encoding selection instead of first-match dispatch (Dict no longer always beats FSST regardless of size). ([1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
+- `FsstEncodingDecoder` no longer throws on valid files with an all-default (empty) `vortex.fsst` metadata segment. ([1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
+- `FsstEncodingEncoder` writes symbol tables in the order the Rust reference requires; previously an out-of-order table could fail to open in the JNI/Rust reader. ([95e0dfb4](https://github.com/dfa1/vortex-java/commit/95e0dfb4))
 
 ### Performance
 
-- `FsstEncodingEncoder` replaces its fixed 2-byte bigram symbol table with iterative FSST-paper-style training (longest-match-first parsing, gain-ranked candidate refinement over several passes), producing variable-length 1–8 byte symbols instead of a fixed 2-byte cap. Also narrows the `uncompressed_lengths`/`codes_offsets` metadata buffers to the smallest ptype that fits the actual data (previously always 4-byte `I32`) using wire-format fields that already existed for this. ([95e0dfb4](https://github.com/dfa1/vortex-java/commit/95e0dfb4), [1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
-- `FsstEncodingEncoder`'s symbol-match lookup replaces a `HashMap<SymbolCandidate, Integer>` (boxing a record key on every probe) with a flat open-addressing table over primitive arrays; training sampling switches from "first N rows" to the same stratified stride sampling `CascadingCompressor` uses elsewhere, avoiding bias on sorted/clustered input. ~18–23% faster encode on incompressible data, ~10% on repetitive text. ([4a3fa0a9](https://github.com/dfa1/vortex-java/commit/4a3fa0a9))
+- `FsstEncodingEncoder`: iterative symbol-table training (variable-length 1–8 byte symbols, was a fixed 2-byte bigram scheme) and narrower metadata buffer ptypes. ([95e0dfb4](https://github.com/dfa1/vortex-java/commit/95e0dfb4), [1bbc3549](https://github.com/dfa1/vortex-java/commit/1bbc3549))
+- `FsstEncodingEncoder`: non-boxing symbol-match lookup and stratified training-sample selection. ([4a3fa0a9](https://github.com/dfa1/vortex-java/commit/4a3fa0a9))
 
 ## [0.12.2] — 2026-07-12