Extract release-notes voice into shared, mechanically enforceable rules

[williamthorsen]

Problem

The summarize-change skill's ## What guidance still produces verbose, mechanism-heavy entries — even after #489's sharpening pass. PR williamthorsen/node-monorepo-tools#387 shows the failure mode: a ~120-word ## What that names schema fields the reader has never seen (description, body, breaking, audience: 'skip'), internal files (.meta/changelog.json), and internal versioning ("v1 supports… for a future reclassification feature"). It passes the post-#489 release-notes test on a literal-checklist read but fails the underlying purpose: A release-notes reader will skip it.

The recurring failure mode is soft tests applied to a verbose draft. The agent reads the rules, drafts something that nominally passes them on a literal check, and ships. New rules layered on the same frame won't catch this; the frame itself needs replacing.

The shipped version after manual rewrite was 17 words: "Allows release-kit consumers to skip or correct historical changelog entries by means of an overrides file." The entry is short not because brevity is a constraint but because the detail belongs in the PR, not the changelog.

Context

Audience and destination:

• The PR's ## What section is extracted into the changelog (every type except fmt) and, for public-tier work types, into release notes.
• The reader is glancing through entries in 2–5 seconds. They have no project-internal context.
• Audience routes by tier (per work-types.json): Public-tier readers are end-users; other-tier readers are developers. Both are glancing readers.

Cross-skill ripple: The current ## What voice guidance lives inline in summarize-change/SKILL.md. commit/SKILL.md already cross-references summarize-change as the canonical voice statement, so tightening here transitively improves commit-body quality. Extracting the principle into a shared file makes the cross-reference structurally honest.

Why #489 didn't suffice: The soft tests (release-notes test, ~100-word soft ceiling) can be passed by a literal-checklist read of a verbose draft. The fix needs rules tight enough that a verbose draft cannot satisfy them mechanically.

No skill-content test framework. The agents package's test suite covers code, not skill semantics. Acceptance is by inspection of the rewritten guidance and by the next several PRs' ## What quality.

Solution

Extract the voice principle into a new shared data file, replacing the existing ## What block with a thin pointer. The reframe operates on three axes:

1. Frame. Lead with the glancing reader and the principle that detail is routed, not omitted. The PR carries the full story; cutting from the entry doesn't lose information, it puts it where it belongs. Audience routes by tier with work-types.json as the source of truth.

2. Two mechanically enforceable rules:

   • Per-sentence outcome test. Each sentence must describe what the change means for the reader: An outcome, a stated invariant worth confirming (e.g., "behavior is unchanged"), or migration info. Mechanism, internal naming, refactor mechanics, internal counts, and output-format details fail the test and are cut. Indirect outcomes (reliability, performance) are permitted only if specific — "more reliable progress visibility during long runs" passes; "improves reliability" is generic puffery and is forbidden.
   • Identifier ban. Only top-level user-configurable surface (package names, CLI commands and flags, top-level config-file paths, public-API endpoints) may appear. Schema field names, default values, internal file paths, function/type names, internal subsystem names, internal versioning, and output-format details are banned. The one exception: A removed user-facing identifier may be named for migration ("the --fix-low flag is replaced by …").

3. Length. As long as needed to convey outcomes, invariants, and migration info — and not one word longer. The per-sentence test is the only check; word counts and sentence counts are not the rule.

Structural changes:

• Create packages/agents/content/skills/_data/release-notes-voice.md carrying the frame, the two rules, the cross-type one-liner examples, and worked Bad/Good pairs (rename, low-action feature, internal-tier, mechanism-cut, over-elaborated fix, TMI feature).
• Slim the ## What curly-brace block in summarize-change/SKILL.md to a thin pointer plus ## What-specific framing (this section becomes a changelog/release-notes entry; route mechanism to ## Details). Remove the previous inline rules, audience constraint, release-notes test, length target, voice paragraph, cross-type examples, and Bad/Good pairs (subsumed by the shared file).
• Update the voice paragraph in commit/SKILL.md to point to the new shared file (replacing the current cross-reference to summarize-change). Add the distinction that the first paragraph of the commit body must stand alone as the changelog/release-notes entry; subsequent paragraphs may elaborate for the engaged reader.

Out of scope (related, but separable): commit/SKILL.md lines 60–62 enumerate the work-type tiers verbatim, duplicating work-types.json. This is the same source-of-truth concern but lives in a different section. Tracked as #542.

Acceptance criteria

• A new file packages/agents/content/skills/_data/release-notes-voice.md exists and carries: The reader/audience frame, the detail-is-routed principle, the two rules (per-sentence outcome test and identifier ban with the user-configurable-surface allowlist), the length statement, the cross-type one-liner examples, and the worked Bad/Good pairs.
• The ## What curly-brace block in summarize-change/SKILL.md is replaced with a thin pointer to the shared file plus ## What-specific framing. The previous inline rules and examples are removed.
• The voice paragraph in commit/SKILL.md points to the shared file as the canonical voice source and includes the "first paragraph stands alone" distinction.
• Audience-by-tier guidance in the new shared file references work-types.json rather than enumerating types inline.
• The per-work-type one-line examples (fix:, feat:, internal:, refactor:, deps:) are present in the shared file unchanged in voice from the current versions.
• The new guidance is tight enough that an agent can fail it on a literal-checklist read (the per-sentence test and identifier ban are mechanical). Verified by inspection of the rewritten guidance and by the next 3–5 feature/fix PRs' ## What quality.

[williamthorsen]

Adding evidence and a refinement.

Second data point. PR williamthorsen/node-monorepo-tools#383 (package rename, audit-deps → v11y-check) shipped a ## What with the same failure pattern as #387. Original, ~120 words:

Renames the package from audit-deps to v11y-check. Consumers run a different CLI command going forward — v11y-check rather than audit-deps/@williamthorsen/audit-deps — and the default config path moves from .config/audit-deps.config.json to .config/v11y-check.config.json. The seven historical audit-deps-v* tags from the prior @williamthorsen/audit-deps releases (v0.2.0 through v0.6.1) are declared as a legacy identity of the renamed workspace, so the next release continues the existing version stream rather than starting from a synthetic baseline. Nothing publishes from this branch directly; the consumer-facing change reaches npm when v11y-check ships its first release.

Manually rewritten just now to ~60 words:

The package previously published as @williamthorsen/audit-deps has been renamed to v11y-check. The CLI command is now v11y-check, and the default config file is .config/v11y-check.config.json. Existing users should install v11y-check in place of @williamthorsen/audit-deps, rename their config file, and update any scripts that invoke audit-deps. Behavior is unchanged.

The mechanism detail (legacyIdentities, the seven historical tags, the publish-timing footnote) wasn't elaborating the rename — it was burying it. Same change-set, half the length, all reader signal. Two consecutive PRs producing drafts that satisfy the post-#489 checklist while violating the aim makes the pattern look representative, not anomalous.

Weighting the four proposed reframes.

1. Identifier prohibition — strongest. Concrete, syntactically falsifiable, catches the failure mode without relying on the writer to honestly self-assess. The rule as stated in the issue ("only top-level user-configurable names; schema fields, internal versioning, internal file paths are out") would have caught both #383 Allow commit prefixes to be configured for user and for repo #387 (description, body, audience: 'skip') and Allow commit prefixes to be configured for user and for repo #383 (legacyIdentities, audit-deps-v* tag prefix, v0.2.0 through v0.6.1) on a literal read.
2. Single-sentence draft mandate — strong. Forces explicit triage. Pair with a per-sentence word ceiling (~25 words) so the rule cannot be gamed by writing one run-on sentence.
3. Hard word ceiling at 40 — backstop. Forces compression but doesn't address the framing bug — mechanism detail compresses too. Useful only in combination with Build orchestration visualizer with retro game aesthetic #1 or CODY-1: Scaffold orchestration visualizer foundation (Phases 0–3) #2.
4. Reader-simulation step — aligned, weak as enforcement. Right test, but agent-authors don't honestly simulate hostile readers. Encode the simulation's outcomes as syntactic rules instead of relying on the simulation itself.

The agent that wrote both bad drafts had access to the post-#489 guidance and rationalized past it. The fix needs to be one a draft can fail on a syntactic read; #1 is the only candidate that meets that bar by itself. #2 meets it when paired with the per-sentence ceiling. #3 and #4 leave the rationalization door open.

One small reframe extension. "Useful or useless, no middle ground" is the right pivot. It can be sharpened by inverting the writer's prompt:

The reader's default action when scanning a release-notes list is to skip. The writer's job is not to inform — it is to prevent skipping. A long entry achieves the opposite of its intent.

"What should I include?" invites elaboration. "What would cause this to be skipped?" invites cutting. Same content, opposite gradient.

Worked-example library. The post-#489 skill has one Bad/Good pair. Adding #387's and #383's before/after pairs would give curators three grounded examples — a stronger anchor than rule-following for a failure mode where the writer's instinct is the bug.