Reframe summarize-change `## What` guidance around the outside-reader audience

[williamthorsen]

Problem

The summarize-change skill produces ## What sections that frequently sprawl, mix headline with diff inventory, use project-internal jargon (file paths, function names, process references like "after the simplifier review"), and read as PR-author monologues rather than as entries an outside reader would scan.

This is felt during nearly every PR. The current guidance mentions the release-notes destination but treats it as a parenthetical fact ("This section is extracted verbatim into the PR body, which feeds release notes…"). Agents and humans following the guidance absorb that sentence without internalizing the audience constraint it implies. The result: ## What sections that read as internal engineering changelogs scoped to the project's vocabulary, not as entries that work for a reader without project context.

Context

Skill source: packages/agents/content/skills/summarize-change/SKILL.md. The ## What section guidance lives in the {curly-brace block} immediately under the ## What heading in the Output format (currently lines ~53-72; subject to drift).

Downstream pipeline that consumes the section:

• summarize-change writes ## What into a change-summary artifact.
• create-pr extracts the change-summary content from ## What onward as the PR body.
• The PR body becomes changelog input for every type except fmt (the universal destination) and release-notes input for changes that meet the release-notes threshold (the elevated destination — a subset of the changelog feed).
• The changelog reader is an outside developer scanning what shipped after a version bump. The release-notes reader is an end user scanning to decide whether the version's changes affect them.

The current guidance has the right principles (release-notes voice, scan-readable, self-contained) but does not operationalize them sharply enough. Specifically:

• "Scan-readable in ~10 seconds" has no concrete length target.
• "Self-contained" can be misread as "covers all sub-changes in the PR" rather than "fully conveys the headline accomplishment."
• No anti-pattern callout for diff-inventorying.
• No explicit ban on internal identifiers (file paths, function names, process references).
• The destination claim is mentioned in a parenthetical, not as the defining audience constraint.

Considerations

• Backward compatibility: the change is to guidance text only — no skill API changes, no behavioral changes to other skills. Existing PRs and release notes are unaffected.
• Distribution: the source file is generated/distributed to ~/.claude/skills/summarize-change/SKILL.md (and equivalents for other harnesses) on install/sync. Edits flow through the standard install pipeline.
• Cross-skill ripple: the commit skill (packages/agents/content/skills/commit/SKILL.md) tells writers to follow summarize-change's ## What section voice for commit bodies. So the proposed change improves commit-body quality transitively — a positive externality, not a regression. The existing cross-reference in commit/SKILL.md already points to summarize-change for the canonical voice statement; no separate edit to commit/SKILL.md is required.
• Examples already in the guidance: the per-work-type one-line examples (e.g., feat: "Adds support for exporting reports as CSV.") are already short and on-voice; they don't need to change. Only the surrounding instruction needs sharpening.
• No skill-content test framework: the agents package's test suite covers CLI/library code, not skill-content semantics. There is no test harness that would validate this change. The acceptance criteria therefore include no automated-test criterion.
• The change is itself documentation: no separate documentation update is required.

Solution

Restructure the ## What curly-brace block to:

1. Lead with the audience constraint as the defining frame (not as a parenthetical fact about destinations).
2. Name both downstream readers explicitly — the outside developer scanning the changelog (universal destination), and the end user scanning release notes (elevated destination) — unified by the question both arrive with: "what shipped?"
3. Replace the existing two preamble paragraphs and the "Because the reader sees this section without the diff, three things follow from the voice:" transition + its three bullets ("Describe the accomplishment", "Scan-readable", "Self-contained") with a single cohesive preamble that subsumes them. The new preamble's release-notes test and length target operationalize the same constraints more sharply, so carrying the older bullets alongside would create overlapping checklists that compete for attention.
4. Add an explicit release-notes test as a bulleted checklist the writer applies before considering ## What finished.
5. Add a concrete length target (~100 words / one paragraph soft ceiling).
6. Add an additional Bad/Good pair illustrating the diff-inventory + project-internal-voice failure mode.

The per-work-type one-line examples and the existing Bad/Good pair are preserved unchanged.

The full text of the rewritten preamble is specified in the implementation plan.

Acceptance criteria

• The ## What curly-brace block in packages/agents/content/skills/summarize-change/SKILL.md leads with the audience constraint, naming both the changelog reader (outside developer, universal destination) and the release-notes reader (end user, elevated destination), unified by the "what shipped?" question.
• The block includes an explicit release-notes test — a bulleted list of mental checks covering: would-someone-without-context-understand, internal-identifier scan, process-reference scan, 10-second scannability.
• The block includes a length target (~100 words / one paragraph soft ceiling) so writers have a concrete check to fail against.
• The block includes an additional Bad/Good pair illustrating the diff-inventory + project-internal-voice failure mode and its corrected version.
• The previous "Because the reader sees this section without the diff, three things follow from the voice:" transition and its three sub-bullets are removed (their content is subsumed by the new preamble — keeping them would create overlapping checklists).
• The per-work-type one-line examples (fix:, feat:, internal:, refactor:, deps:) are preserved unchanged.
• The existing Bad/Good pair (author's standpoint vs reader's standpoint) is preserved unchanged.
• The ## What heading itself, the ## Why and ## Details sections, the front-matter, the file's other sections (Guidance, Frontmatter inference, As a PR description, Saving), and the leading { of the curly-brace block remain untouched.