docs: Capture release-note editorial and validation guidance

.github/skills/release-notes/SKILL.md

@@ -28,6 +28,24 @@ changes. Do not substitute a schema stub or defer feature selection to the
 component PRs. Give component writers the relevant candidate entries with
 their scores and reasons rather than a slim list of titles and labels.
 
+Read previous component announcements before selecting or rewriting features.
+Use their voice, structure, length, and selection as references.
+Audit the pinned shipped changes and source tests. Apply the [quality bar](references/quality-bar.md)
+for omission discovery and explicitly requested catch-up coverage.
+Follow the [editorial rules](references/editorial-rules.md) for naming,
+audience, evidence, ordering, and companion reports.
+
+Use the [format template](references/format-template.md) for article-level
+preview setup and accurate section labels. Preserve each feature's actual
+requirements and metadata-derived safety notices.
+
+Validate claims through `validate-code-samples`, but keep temporary projects,
+checkers, and results in session or scratch storage by default.
+Commit maintained fixtures only when explicitly requested or already agreed
+in the task scope. Follow [PR layout](references/pr-layout.md) for publication
+scope and source-branch updates. Bound research to the changed claims.
+For prose-only edits, run the smallest existing documentation checks, not code builds.
+
 Before finalizing the milestone, run `review-release-notes` against the
 `changes.json`, `features.json`, and completed component drafts on their
 branches (or the base branch after they merge). Resolve noteworthy omissions

.github/skills/release-notes/references/changes-schema.md

@@ -231,4 +231,4 @@ The markdown release notes are a curated subset informed by these JSON files:
 - `features.json` helps rank which shipped changes are worth calling out
 - Markdown only covers features worth calling out
 - The agent reads `changes.json` and/or `features.json` to decide what to write about
-- If a feature isn't in `changes.json`, it must not appear in the markdown
+- Claims of newly shipped changes must trace to this milestone's `changes.json`. See [the fidelity rule](quality-bar.md#the-fidelity-rule) for explicitly requested catch-up coverage and full-cycle reports.

.github/skills/release-notes/references/editorial-rules.md

@@ -8,6 +8,7 @@ Tone, attribution, and content guidelines for .NET release notes.
   - ✅ `ProcessExitStatus provides a unified representation of how a process terminated.`
   - ❌ `Previously, there was no way to determine how a process terminated.`
 - When context about the prior state is needed, keep it brief — one clause, then pivot to the new capability
+- Celebrate important capabilities through concrete developer possibilities. Put benefit-focused narrative in the body, not invented feature branding in headings.
 - **Don't editorialize beyond the facts** — state what concretely changed ("enabled by default", "no longer requires opt-in") rather than making claims you can't back up ("ready for production use", "signals maturity"). If a PR removes a preview attribute, say that. Don't interpret it as a promise.
   - ✅ `Runtime-async is now enabled by default for anyone targeting net11.0.`
   - ❌ `This signals that runtime-async is ready for production use.`
@@ -33,7 +34,12 @@ Tone, attribution, and content guidelines for .NET release notes.
 
 ## Entry naming
 
-- Prefer a **brief description** of what the feature does over the API name alone
+- Use the **established feature name** when one exists, especially for long-running preview features. If `release-notes/features.json` lists an `official_name`, use that in headings and prose. Treat aliases as match-only metadata, not as the default wording.
+  - ✅ `## Unsafe Evolution remains a preview feature in .NET 11`
+  - ✅ `## Unsafe Evolution adds clearer diagnostics in Preview 3`
+  - ❌ `## Memory Safety v2 adds clearer diagnostics in Preview 3`
+  - ❌ `## Unsafe code adds clearer diagnostics and annotations`
+- When no established name exists, prefer a **brief description** of what the feature does over the API name alone
   - ✅ `## Support for Zstandard compression`
   - ✅ `## Faster time zone conversions`
   - ❌ `## ZstandardStream`
@@ -45,40 +51,44 @@ Tone, attribution, and content guidelines for .NET release notes.
 - Avoid anthropomorphic or club-like transition verbs such as `joins` when a more literal term is available. Prefer `moves to`, `is now in`, `adds support for`, or `supports`.
   - ✅ `## Zstandard moved to System.IO.Compression and ZIP reads validate CRC32`
   - ❌ `## Zstandard joins System.IO.Compression and ZIP reads validate CRC32`
-- Use the **established feature name** when one exists, especially for long-running preview features. If `release-notes/features.json` lists an `official_name`, use that in headings and prose. Treat aliases as match-only metadata, not as the default wording.
-  - ✅ `## Unsafe Evolution remains a preview feature in .NET 11`
-  - ✅ `## Unsafe Evolution adds clearer diagnostics in Preview 3`
-  - ❌ `## Memory Safety v2 adds clearer diagnostics in Preview 3`
-  - ❌ `## Unsafe code adds clearer diagnostics and annotations`
 - Keep headings concise — 3–8 words
 
 ## Benchmarks
 
-- Use **exact data** from PR descriptions — never round, approximate, or paraphrase
-- State what was measured and the hardware/workload context
+- Use source-backed measurements. Preserve exact values when quoting raw results.
+- Accurate author-provided summaries can use rounded values for readability. Check them against the source and avoid invented precision.
+- Name the metric: allocated bytes, allocation counts, retained heap, peak memory/RSS, CPU time, or elapsed time.
+- State the workload, hardware, baseline, and comparison cohort. Distinguish source-built payloads from official SDKs. Identify changed compiler, library, runtime, or packaging inputs.
 - Include specific before/after measurements when compelling
+- Preserve regressions and limitations. Do not sum unrelated workload deltas or claim universal speedups or future performance.
 - Do **not** embed full BenchmarkDotNet tables — summarize in prose
 
+Separate public-library optimizations from compiler, compiler services (FCS), and IDE memory improvements.
+FSharp.Core optimizations can benefit compiled applications.
+State each audience and adoption path. Group related compiler changes across PRs into coherent categories with representative evidence.
+
 ## What to include
 
 - **Shared audience filter** — apply the 80/20 rule from `editorial-scoring`; don't redefine a competing threshold here. Keep narrower items only when the broader audience can still see why they matter.
-- **The two-sentence test** — if you can only write two sentences about a feature, it's probably an engineering fix, not a feature. Cut it. A community contribution or breaking change can lift a borderline entry, but "fixed an internal bug that happened to be visible" is not a feature.
-- **Headlines should convey value** — a heading like "GC regions on macOS" doesn't tell the reader whether this is good or bad. Prefer headings that hint at the benefit: "GC regions enabled on macOS" or "Server GC memory model now available on macOS."
+- **The two-sentence test** — use a thin explanation as a signal to inspect reader value, not an automatic length cutoff. Apply the shared rubric to compact capabilities and author-facing foundations. An internal fix alone does not justify a feature.
+- **Headlines should convey value** — preserve established names first. Without an established name, prefer headings that state the capability or benefit. A heading like "GC regions on macOS" doesn't tell the reader whether this is good or bad. Prefer "GC regions enabled on macOS" or "Server GC memory model now available on macOS."
 - **Product-boundary rule** — exclude higher-level IDE, editor, or design-time tooling features from product notes unless the release is specifically about that tooling surface. For example, a Razor editor code action should not be presented as an ASP.NET Core feature just because it is adjacent to the web stack.
 - **TODO for borderline entries** — when a feature might deserve inclusion but you lack data to justify it (benchmark numbers, real-world impact, user demand), keep the entry but add an HTML `<!-- TODO -->` comment asking for the missing information. This is better than silently including a vague claim or silently cutting something that might matter. The TODO should state what's needed and link to the PR where the data might live.
 - **Breaking changes are separate from hype** — a breaking change can be important even when it is not exciting. Keep the score honest; use `breaking_changes: true` to preserve a short callout instead of inflating the item into a headline feature.
 - **Clusters can be stronger than the parts** — several related low-score items can justify one section when together they tell a clear story. Keep the individual scores honest, then merge them into one writeup instead of emitting several weak mini-features. Good examples include a group of "Unsafe evolution" changes or multiple runtime entries prefixed with `[browser]`.
 
 ## Feature ordering
 
-Order features using three tiers, applied in order:
+Follow explicit user priorities first. Otherwise, use these three tiers:
 
 1. **Broad interest first** — features most developers will care about go at the top. A new `RegexOptions` value ranks above an ARM64-only instruction set.
 2. **Cluster related features** — group related items together even if they differ in importance. All Regex work in one block, all System.Text.Json work in another, all JIT work together. Readers scan by area.
 3. **Alphabetical within a cluster** — when features within a cluster have roughly equal weight, alphabetical order makes them scannable.
 
 Use PR and issue reaction counts as a signal for tier 1, but apply judgment — a niche feature with 100 reactions may still rank below a broadly useful one with 10.
 
+Keep the opening list and body in the same order. Match section length to importance and predecessor articles, not a fixed feature quota.
+
 ## Community attribution
 
 ### Inline
@@ -153,6 +163,9 @@ If the fix is for a feature that was never really announced or is still obscure
 
 ## Preview-to-preview deduplication
 
+Read the published predecessor articles, not only the current draft or PR titles.
+Omit unchanged material and unnecessary carry-forward reminders, including preview-status reminders.
+
 When prior previews already documented a feature, don't repeat the same information. But **do** document significant state changes in the current preview. A feature that was introduced as opt-in in P1 and is now enabled by default in P3 is new news — document the change in state, not the feature from scratch.
 
 Ask: "What changed about this feature since the last preview's release notes?" If the answer is meaningful to users (enabled by default, no longer experimental, major perf improvement, new sub-features), write about that. If the answer is just "more PRs landed in the same area," skip it.
@@ -164,6 +177,27 @@ Examples:
 - ❌ Repeating the full explanation of what runtime-async is from P1 (already documented)
 - ❌ "More JIT optimizations landed this preview." (no specific news)
 
+## Companion reports and supplied articles
+
+- Keep a useful feature summary when adding a deeper report. Add a concise sibling link that explains the report's value.
+- When requested or important, add an inline read-more link in the opening TOC without changing feature order.
+- Check supplied article packages for required assets, all references, and provenance before import.
+- Copy only the approved article and required media. Follow the existing media layout and retain stable source and citation links.
+- Do not run arbitrary supplied generators. Publication approval does not include datasets, generators, READMEs, archives, or experiment scaffolding.
+- Report missing methodology or raw-result references while the user can retrieve them. Do not invent evidence URLs.
+- If evidence remains missing, obtain explicit publication approval and record the limits. That approval applies only to that report.
+- Describe author-provided or source-built measurements accurately. Publication approval alone does not establish independent verification or public reproducibility.
+
+Keep the milestone index navigation-only unless explicitly requested otherwise.
+Follow [the index contract](format-template.md#readmemd-index-file), not an inferred prohibition from one observed example.
+
+## Link validation
+
+- Check relative links, heading anchors, images, remote PR/source targets, and redirects.
+- If GitHub page checks are blocked, use the authenticated API to establish object existence.
+- Do not count ignored targets or HTTP 429 as confirmed availability. Record unavailable checks separately from passed checks.
+- After renaming headings or moving or deleting files, update affected references and relative media paths.
+
 ## Filtered features
 
 When you cut a feature for failing the 20/80 rule or two-sentence test, record it in an HTML comment block in the output file. This creates a learning record — future runs and human reviewers can see what was considered and why it was excluded.

.github/skills/release-notes/references/format-template.md

@@ -94,8 +94,8 @@ when generating and completing the index:
 1. Preallocate an unlinked entry for every expected component file listed in
    `component-mapping.md` on the base branch, including components without
    noteworthy changes. Do not link a file that exists only on another branch.
-2. Each component PR links exactly its own entry when adding the matching file
-   (and any matching validation samples). Before the base PR leaves draft,
+2. Each component PR links exactly its own entry when adding the matching file.
+   Before the base PR leaves draft,
    verify that every expected component file exists and is linked exactly once.
 3. Keep Libraries, Runtime, SDK, MSBuild, and NuGet before the grouped sections.
 4. Use **Languages** for language release notes and
@@ -131,11 +131,22 @@ Known component docs links:
 ## Section rules
 
 1. **TOC at top** — every feature gets a linked entry
-2. **One paragraph of context** — what the feature does and why it matters in concrete terms, with PR/issue links; avoid inferred feelings or marketing-style claims
-3. **Code sample** — show the feature in use
-4. **Feature ordering** — highest customer impact first
+2. **Context proportional to importance** — name the audience and concrete developer possibilities, with PR/issue links. Positive benefit-focused narrative is welcome when evidence supports it.
+3. **Useful scenario** — show substantial supported usage, or representative measurements for default-enabled and grouped performance changes. Validation projects stay in scratch storage unless maintained fixtures are in scope.
+4. **Feature ordering** — explicit user priorities first, otherwise reader impact. Keep the TOC and body aligned.
 5. **Upgrade guidance near the end** — keep version-to-version breaking changes separate from changes affecting only preview users. `breaking_changes: true` flags migration significance, not which section an item belongs in; see below.
-6. **Preview feature callout** — when a feature is listed in `release-notes/features.json`, start its section with the standard blockquote callout from that file
+6. **Preview requirements** — apply each feature's actual opt-ins and metadata-derived safety notices, as described below.
+
+### Preview setup
+
+Define shared component-specific opt-ins once near the article opening.
+For example, F# language-version setup can apply to several sections.
+Label affected sections **Preview** or refer to that setup without repeating XML or CLI flags.
+Keep default-enabled improvements distinct and state any different per-feature requirements.
+
+When `release-notes/features.json` provides a standard callout, preserve its safety information, including broader product-preview warnings.
+Shared setup does not replace those notices with a language-version assumption.
+Use compact section labels only where they preserve the applicable requirements and warnings.
 
 ## Upgrade guidance
 
@@ -146,8 +157,8 @@ Use **Changes since the previous preview** for migrations that only affect code
 The [incremental API diff](api-verification.md#review-incremental-api-diffs-for-preview-upgrades) and maintained samples can reveal migration candidates, but do not determine which baseline they break.
 
 Cover these when they apply. They tend to surface only when an existing project is actually upgraded
-to the new build, which is one of the reasons
-[`validate-code-samples`](../../validate-code-samples/SKILL.md) upgrades the component's maintained sample set under `release-notes/<major>.0/samples/<component>/`:
+to the new build. [`validate-code-samples`](../../validate-code-samples/SKILL.md)
+uses scratch projects by default and upgrades maintained component samples when they are in scope:
 
 - **Renamed APIs**, especially renames that invert meaning (`EnableX` becoming `DisableX`). Show the
   before and after, and state the new default explicitly.

.github/skills/release-notes/references/pr-layout.md

@@ -16,6 +16,12 @@ The set of components and their release notes files is defined in [`component-ma
 - Never link an entry to a file absent from that branch. Keep unlinked entries for pending component PRs; once all component PRs merge, verify that every expected entry links to its existing file. Retain push and PR link checks throughout.
 - The milestone landing page `{version}.md` (for example, `11.0.0-preview.4.md`) is **not produced by this skill**. The .NET release team generates it through separate artifacts-publishing automation, so the agent leaves it alone on every branch.
 
+Publication scope is the component article, its own index link, and explicitly approved companion reports or required media.
+Validation alone does not authorize repository fixtures or other experiment artifacts.
+Add or change maintained fixtures only when explicitly requested or already agreed in the task scope.
+Do not silently delete existing files.
+Skill-policy updates belong in a separate documentation PR, not a release-article PR.
+
 ## Creating the PRs
 
 Order matters, and two of these steps fail silently.
@@ -25,7 +31,7 @@ Order matters, and two of these steps fail silently.
    the component branches but **not** the base branch — verifying with that pattern reports success
    while the base branch is still local-only.
 2. **Confirm each component branch starts from the base branch commit.** Each component PR should
-   show only its component file, any matching validation samples, and its single README link change;
+   show only its component file, its single README link change, and approved companion material or maintained fixtures;
    it should not restate shared metadata or other components' entries. If the base branch moves,
    merge it into the component branch before updating the entry and verify the diff again.
 3. **Open the base PR against `main`**, then the component PRs against the base branch.
@@ -37,6 +43,15 @@ Order matters, and two of these steps fail silently.
    edits conflict as owners merge, retain all previously merged links and add only the current
    component's link.
 
+### Updating and reporting
+
+- Update an existing PR's head branch only. Preserve its draft state and base unless explicitly authorized otherwise.
+- Use ordinary commits and non-force pushes. Do not amend commits or publish directly to the target branch or `main`.
+- Leave promotion and merging to the authorized owner. Do not merge as part of a documentation edit.
+- Report the actual branch and commit SHA. Distinguish local, committed, pushed, and merged state.
+- Report whole-PR file counts and additions/deletions against the base, not only the latest patch.
+- Bound research to the requested changes. For prose-only edits, use the smallest existing Markdown and reference checks, not code builds.
+
 ### gh pr edit does not work on this repo
 
 `gh pr edit` fails against `dotnet/core` with a Projects (classic) GraphQL deprecation error and