Problem
The summarize-change skill's "What" section consistently produces implementation-focused descriptions instead of outcome-focused summaries. Even the author of the code has difficulty understanding these descriptions — they read like compressed changelogs rather than summaries.
The details are already included later in the change summary (in the ## Details subsections). The "What" section should not duplicate or preview them. Instead it should give the reader the essential information upfront, so they can decide whether to read further.
Example of current output:
Wire up the existing suites stub on PreflightCollection end-to-end: pass through export resolution, add a shared validator for name-collision and referential-integrity checks, integrate validation into the compile path, and expand suite names in CLI checklist selection.
This describes four internal code changes compressed into one sentence. A reader unfamiliar with the codebase cannot quickly grasp what was done. Even the author finds it hard to parse.
Better:
Enables the suites feature, allowing collections of checklists to be run by suite.
The improved version leads with the capability in plain language. Implementation details are already covered in ## Details.
Cause
The skill's guidance for the "What" section is minimal: {1-3 sentences describing the changes}. There is no instruction to prioritize outcomes over mechanics, or to avoid restating details that appear later in the summary.
Solution
Update the ## What guidance in the summarize-change skill to follow newspaper style: essential information first, progressively greater detail in later sections. Specifically:
- Lead with the outcome — what capability was added, what behavior changed, what problem was fixed. Use plain language that a reader can understand in one pass, even without context on the codebase.
- Mention key components only when they add clarity — e.g., "Makes the username optional in the
xyz function" is helpful; listing every module touched is not.
- Do not preview the Details section — implementation mechanics (which functions were added, which modules were wired together, which validators were introduced) belong exclusively in
## Details. The "What" section should never duplicate them.
- Keep it short — one sentence is ideal, two is fine, three is the maximum. If it takes more than that, the description is too detailed for this section.
The change summary as a whole follows newspaper structure:
## What — the headline (outcome, plain language)## Why — the context (motivation, background)## Details — the full story (implementation mechanics, organized by work type)
Acceptance criteria
Must have
- ✅
The ## What guidance explicitly instructs agents to lead with the outcome or capability, not the implementation (done in e581005)
- ✅
The guidance includes a positive example (outcome-first) and a negative example (implementation-first) to clarify the distinction (done in e581005)
- ✅
The guidance explicitly states that implementation details belong in ## Details and should not be previewed in ## What (done in e581005)
Should have
- ✅
The guidance references newspaper style as the structural model for the entire change summary (done in 9aa33a9)
- ✅
Existing Details subsection guidance unchanged (verified)
Bonus (added during implementation)
- ✅
Outcome-first guidance added to commit-format.md body formatting rules (done in 19d6e9d)
- ✅
condense-branch synthesize path reinforced with outcome-first framing19d6e9d)
Problem
The
summarize-changeskill's "What" section consistently produces implementation-focused descriptions instead of outcome-focused summaries. Even the author of the code has difficulty understanding these descriptions — they read like compressed changelogs rather than summaries.The details are already included later in the change summary (in the
## Detailssubsections). The "What" section should not duplicate or preview them. Instead it should give the reader the essential information upfront, so they can decide whether to read further.Example of current output:
This describes four internal code changes compressed into one sentence. A reader unfamiliar with the codebase cannot quickly grasp what was done. Even the author finds it hard to parse.
Better:
The improved version leads with the capability in plain language. Implementation details are already covered in
## Details.Cause
The skill's guidance for the "What" section is minimal:
{1-3 sentences describing the changes}. There is no instruction to prioritize outcomes over mechanics, or to avoid restating details that appear later in the summary.Solution
Update the
## Whatguidance in thesummarize-changeskill to follow newspaper style: essential information first, progressively greater detail in later sections. Specifically:xyzfunction" is helpful; listing every module touched is not.## Details. The "What" section should never duplicate them.The change summary as a whole follows newspaper structure:
## What— the headline (outcome, plain language)## Why— the context (motivation, background)## Details— the full story (implementation mechanics, organized by work type)Acceptance criteria
Must have
The(done in## Whatguidance explicitly instructs agents to lead with the outcome or capability, not the implementatione581005)The guidance includes a positive example (outcome-first) and a negative example (implementation-first) to clarify the distinction(done ine581005)The guidance explicitly states that implementation details belong in(done in## Detailsand should not be previewed in## Whate581005)Should have
The guidance references newspaper style as the structural model for the entire change summary(done in9aa33a9)Existing Details subsection guidance unchanged(verified)Bonus (added during implementation)
Outcome-first guidance added to(done incommit-format.mdbody formatting rules19d6e9d)condense-branchsynthesize path reinforced with outcome-first framing19d6e9d)