Issue to solve:
The agent file .github/agents/whats-new-from-release-notes.agent.md, and its skill file whats-new-include-content-rules do not contain an explicet fidelity/preservation rule. As a result the agent can condense source information from relase notes too much and degrade the fidelity and overall helpfulness of the information.
The skill file is entirely about formatting (headings, xrefs, links, phrasing, naming), and the closest thing to a content-preservation instruction is line 42's "Create one include file per feature" — which speaks to file granularity, not content completeness. So the agent was free to condense, and would occasionaly do so, degrading the resulting content.
Here's what should change and where.
Where the gap is:
.github/agents/whats-new-from-release-notes.agent.md — Step 1 (lines 121–129) just says "create one include file per feature" and defers everything to the skill. No preservation directive.
.github/skills/whats-new-include-content-rules/SKILL.md — the "Content rules" section (lines 60–131) governs style/format only. There is no rule against dropping examples, code, or the reasoning that ties prose to code.
Notably, this exact failure — a self-contained code sample (the throwing Validate) that no longer makes sense because its paired example and rationale were dropped — isn't covered by any existing rule.
Recommended changes:
- Add a "Content fidelity / preservation" rule to the SKILL file
Insert a new top-priority subsection under ## Content rules (right after line 61, before "Heading level"):
### Content fidelity — preserve information; do not condense
The What's New article is a **faithful, cumulative** rendering of the source
release notes. Reformat and de-duplicate, but do not summarize away information.
* **Default to preserving all substantive content** from the source section:
every code example, every explanatory sentence, and the reasoning that
connects prose to code. Transfer them into the include file.
* **Never drop one of a set of parallel examples.** If the source shows a
pattern more than once (for example, an attribute-based example *and* an
object-based example), keep **all** of them. Dropping one often removes the
context that makes the others understandable.
* **Keep "why," not just "what."** If the source explains the rationale for a
code construct (for example, why a synchronous method throws), preserve that
explanation next to the code. A code sample must never be left in a state
where it looks contradictory or pointless without its original explanation.
* **Self-containment check:** after writing each include, re-read it in
isolation. If any code sample would look counterintuitive or unexplained to a
reader who has not seen the source notes, restore the missing explanation or
example from the source.
* **You MAY combine overlapping content across previews** so the cumulative
article doesn't repeat itself, but only remove text that is genuinely
redundant — never text that carries unique information or reasoning.
* **When in doubt, keep it.** Prefer transferring the source wording over
rewriting it more tersely. Condensing is only acceptable when it removes
literal duplication.
2. Reinforce it in the agent file's Step 1
Change Step 1 (lines 127–129) from the current terse instruction to something that names fidelity as the governing principle:
Apply those rules to create one include file per feature from the source
release notes.
**Fidelity is the priority.** Transfer the source content faithfully: preserve
every code example, every explanatory sentence, and the reasoning that ties
prose to code. You may reformat, and you may combine overlapping content across
previews to avoid repetition, but do not summarize or drop information. In
particular, never drop one of a set of parallel examples, and never leave a code
sample without the explanation that made it make sense in the source. If a
source section makes sense and the resulting include does not, that is a defect.
3. Add fidelity items to the validation checklist
Add these to the checklist (after line 151) so it's actually enforced at the end:
- [ ] Every code example from the source section is present (none dropped).
- [ ] All parallel/paired examples from the source are retained together.
- [ ] The rationale ("why") for any non-obvious code construct is preserved next to the code.
- [ ] Each include reads correctly in isolation — no code sample looks counterintuitive without the source.
- [ ] Content removed relative to the source is limited to genuine cross-preview duplication.
Associated WorkItem - 598905
Issue to solve:
The agent file .github/agents/whats-new-from-release-notes.agent.md, and its skill file whats-new-include-content-rules do not contain an explicet fidelity/preservation rule. As a result the agent can condense source information from relase notes too much and degrade the fidelity and overall helpfulness of the information.
The skill file is entirely about formatting (headings, xrefs, links, phrasing, naming), and the closest thing to a content-preservation instruction is line 42's "Create one include file per feature" — which speaks to file granularity, not content completeness. So the agent was free to condense, and would occasionaly do so, degrading the resulting content.
Here's what should change and where.
Where the gap is:
.github/agents/whats-new-from-release-notes.agent.md — Step 1 (lines 121–129) just says "create one include file per feature" and defers everything to the skill. No preservation directive.
.github/skills/whats-new-include-content-rules/SKILL.md — the "Content rules" section (lines 60–131) governs style/format only. There is no rule against dropping examples, code, or the reasoning that ties prose to code.
Notably, this exact failure — a self-contained code sample (the throwing Validate) that no longer makes sense because its paired example and rationale were dropped — isn't covered by any existing rule.
Recommended changes:
Insert a new top-priority subsection under ## Content rules (right after line 61, before "Heading level"):
Associated WorkItem - 598905