Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(release): order changelog entries by reader interest and cap their length (#3774)
Maximilian Roos61ec8d5d2ad8
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.mdindex 04ea94d07..a28207cb8 100644--- a/.claude/skills/release/SKILL.md+++ b/.claude/skills/release/SKILL.md@@ -120,13 +120,7 @@ Notable changes to document:**Section order:** Improved, Fixed, Documentation, Internal. Documentation is for help text, web docs, and terminology improvements. Internal is for selected notable internal changes (not everything).-**Within each section, order by impact:**-1. Breaking/behavior changes (affect existing users' workflows)-2. New user-facing features and commands-3. Performance improvements users will notice-4. Minor enhancements and display changes-5. Niche/platform-specific improvements (Nix, Windows-only, etc.)-6. Developer/internal tooling exposed to users+**Within each section, order by reader interest.** The section is the first ordering dimension and is fixed; reader interest is the second, and it decides rank inside a section. A change's class does not: a behavior change nobody asked for ranks below a feature people requested, and a fix every user hits ranks above a platform-specific one. Interest combines how many readers a change reaches with how much it obliges each of them to act, and never counts the effort the change took to build — effort and interest diverge most on the change just finished, which is the one being written up. So a breaking change stays near the top of its section: it reaches few readers, but every one of them has to do something about it. (`/writing-prose` calls this "Calibrate prominence to audience fraction"; restated here because that skill is personal config and isn't in this repo.)**Breaking changes:** Note inline with the entry, not as a separate section:@@ -140,7 +134,16 @@ Skip: internal refactors, test additions (unless user-facing like shell completi**Combine related bullets.** Several PRs that share a theme — e.g. three perf changes that together account for one user-visible speedup — belong in one bullet, not three. The reader cares about the net change, not the PR boundaries. Cite all the PRs in the trailing `([#a](...), [#b](...), [#c](...))` list.-**Be brief.** Each bullet should communicate the user-visible change in 1–3 sentences. Internal-section bullets in particular should be terse — usually one sentence. Drop the "why we did it this way" details unless they materially affect how the user thinks about the change. Code examples and exhaustive `Cmd::stream` / `OnceCell` / `DashMap`-style internals usually don't belong; they live in the PR description.+**Be brief — the ceiling is words, not sentences.** A bullet lands at 40 words or under; the two or three headline entries may reach 80; Internal-section bullets get one sentence. The whole release — every section together, which is what the command below measures — stays under ~1,200 words. Drop the "why we did it this way" details unless they change how the user thinks about the change, and leave code examples and `Cmd::stream` / `OnceCell` / `DashMap`-style internals in the PR description, where the reasoning belongs.++Sentences stretch to fit whatever you want to say; words don't. So measure rather than judge:++```bash+awk '/^## /{if (f) exit; f=1} f' CHANGELOG.md \+ | awk '/^- \*\*/ {n=split($0,_," "); t+=n; c++; printf "%4d %.58s\n", n, $0} END {printf "\n%d entries, %d words, %d avg\n", c, t, c?t/c:0}'+```++**Calibrate against the ceiling, not against the last release.** Length ratchets: each release is drafted beside the previous section, and an abstract rule loses to a concrete neighbouring exemplar every time. Entries grew from 49 to 101 words on average across five releases while this skill said "be brief" throughout. Read the previous section for what it drifted to, then ignore it and write to the ceiling.**No editorial framing.** Describe what changed, not what was wrong with the previous decision in subjective terms. Avoid words like "sledgehammer", "ugly", "noisy", "wrong" applied to past code. State the prior behavior neutrally and the new behavior plainly.@@ -222,12 +225,15 @@ Link when there's substantial documentation the user would benefit from reading**After drafting changelog entries, you MUST spawn a subagent to verify each bullet point is accurate.** This is non-negotiable — changelog mistakes are a recurring problem.+**The gate cuts both ways.** Checking only accuracy pushes every entry longer: "understates" and "not covered" have no counterweight, so each pass adds and none subtracts. That asymmetry is what drove the ratchet above. An entry that is too long, too internal, or ranked above one more readers will notice is reported on the same footing as one that is wrong.+The subagent should:1. Take the list of drafted changelog entries2. For each entry, find the commit(s) it describes and read the actual diff3. Verify the entry accurately describes what changed4. Check for missing changes that should be documented-5. Report any inaccuracies or omissions+5. Check each entry against the length ceiling and the ordering rule+6. Report inaccuracies, omissions, overlong entries, and misordering**Subagent prompt template:**@@ -245,19 +251,25 @@ For EACH entry:2. Read the actual diff, not just the commit message3. Confirm the entry accurately describes the user-facing change4. Flag if the entry overstates, understates, or misdescribes the change+5. Flag if the entry runs over 40 words (80 for one of the two or three headline+ entries), restates the PR description, or explains mechanism the reader cannot+ act on — report these as seriously as an inaccuracy, and quote a shorter+ rewrite that keeps every user-facing claimAlso check:- Are there user-facing changes NOT covered by these entries?- Verify each "thanks @..." attribution (right person, right role — author vs reporter)+- Within each section, is any entry ranked above one that more readers will notice?Report format:- Entry: [entry text]Status: ✅ Accurate / ⚠️ Needs revision / ❌ Incorrect+ Length: [word count] — ✅ / ⚠️ over ceilingEvidence: [what you found in the diff]Suggested fix: [if needed]```-**Do not finalize the changelog until the subagent confirms all entries are accurate.**+**Do not finalize the changelog until the subagent confirms every entry is accurate and within the ceiling.****If verification finds problems:** Escalate to the user. Show them the subagent's findings and ask how to proceed. Don't attempt to resolve ambiguous changelog entries autonomously — the user knows the intent behind their changes better than you do.