Reframe the audience-cascade section in changelog-conventions

Why Care?

A skill rule that contradicts itself is worse than no rule — agents trying to follow it produce documents that are confused on the page because the guidance was confused on the page. The “These are marketing artifacts, not internal documentation” section in changelog-conventions/SKILL.md had this problem: the heading said “marketing all the way down,” and the next paragraph then described a four-audience cascade where only the top of the doc is marketing-shaped and the bottom is engineering-shaped. The two messages fought, and the louder one (the heading) won — pushing entries toward a tone that lost the engineer who’d scrolled past the lede looking for the gnarly bits.

The fix is small but load-bearing for every changelog written from here forward.

What’s New?

The section now opens with the rule it actually means: marketing up top, engineering notes as the narrative unfolds. The opening sequence (lede → Why Care? → What’s New?) is marketing-shaped; it earns the click. The deeper sections (How it Works → Under the Hood → Files Touched / What’s Next / References) are engineering-shaped; they reward the reader who came for substance with the substance. The same document serves all four audience tiers by sequencing the content from broadest to most-specific.

The rewrite added one paragraph that the prior version was missing: the failure mode this rule fights is mixing the voices in the wrong order. Engineering details in the lede lose the general audience. Marketing language in the Under the Hood section feels evasive to the engineer who scrolled there for the technical bits. Naming the failure mode makes the cascade easier to apply — it gives the author a concrete thing to check against, not just a directional preference.

Finally, the paragraph under the audience table picked up an explicit observation that voice itself shifts as the reader descends. The lede speaks to anyone; the Files Touched block speaks to the team. Each audience gets dropped at the right station and the prose meets them there.

Under the Hood

The mechanics already in the skill — the body-shape conventions (Why Care? then What's New?), the voice section, the “show, don’t enforce” ethos — didn’t move. What moved was the framing that those mechanics serve. Before, the framing said “this is marketing.” After, the framing says “this is a cascade from broad to specific, and the voice cascades with it.”

The skill’s other sections compose with this one cleanly:

• Body shape: lead with the previewable sections — codifies the canonical opening order
• Tell a story — frames the structural arc each entry should follow
• Voice — governs the tone in which all four audiences are addressed
• This section — sets the audience model the other three sections serve

The four sections together form the writing discipline; reframing this one tightened the others by removing the contradictory note they were trying to compose with.

Files Changed

• changelog-conventions/SKILL.md — section heading reworded; opening paragraph rewritten; new failure-mode paragraph; “whole point” sentence extended with the voice-shift observation

What’s Next

The same audience-cascade framing is referenced from git-conventions/SKILL.md (commit messages serve the same four audiences) — that cross-reference now points at language that actually says what it means. No other skill files needed touching in this pass.

Reference

• Original commit: da20229 — skill(changelog-conventions): marketing up top, engineering notes as the narrative unfolds
• Related skill section: Body shape: lead with the previewable sections (unchanged, composes with this one)
• Cross-skill tie: [[git-conventions]] §“Commit messages also serve four audiences”