From 969f373558772faa71eb931b19ba22188c9c66b0 Mon Sep 17 00:00:00 2001
From: Marius Storhaug <marstor@hotmail.com>
Date: Sat, 5 Sep 2026 08:30:16 +0200
Subject: [PATCH 1/3] Document PR-based release notes

Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
---
 .../guides/configuring-the-pipeline.md        |  20 ++-
 .../content/guides/versioning-and-releases.md |   5 +
 .../guides/writing-release-note-prs.md        | 148 ++++++++++++++++++
 docs/zensical.toml                            |   1 +
 4 files changed, 170 insertions(+), 4 deletions(-)
 create mode 100644 docs/content/guides/writing-release-note-prs.md

diff --git a/docs/content/guides/configuring-the-pipeline.md b/docs/content/guides/configuring-the-pipeline.md
index b77d4cdf..dd7d9258 100644
--- a/docs/content/guides/configuring-the-pipeline.md
+++ b/docs/content/guides/configuring-the-pipeline.md
@@ -145,13 +145,25 @@ Publish:
 This produces release notes like:
 
 ```markdown
-# 🚀 Add new authentication feature (#42)
+# 🚀 [Feature]: Commands can authenticate without browser callbacks (#42)
 
-This PR adds OAuth2 support with the following changes:
-- Added `Connect-OAuth2` function
-- Updated documentation
+Commands can now authenticate in environments where a browser callback is unavailable.
+
+## Adopting this release
+
+1. Update the module to the released version.
+2. Replace interactive sign-in with the device-code command where browser callbacks are unavailable.
+
+## Release impact
+
+- **Configured label:** `minor`
+- **SemVer change:** Minor.
+- **Version transition:** `v1.4.2` -> `v1.5.0`
 ```
 
+Use [Writing release-note pull requests](writing-release-note-prs.md) for the complete user-facing structure,
+including technical details and relevant issue links.
+
 ### Version-only release names
 
 If you prefer version numbers as release names but still want PR-based notes:
diff --git a/docs/content/guides/versioning-and-releases.md b/docs/content/guides/versioning-and-releases.md
index fe226002..c7be84c0 100644
--- a/docs/content/guides/versioning-and-releases.md
+++ b/docs/content/guides/versioning-and-releases.md
@@ -9,6 +9,11 @@ Process-PSModule orchestrates the module lifecycle through GitHub Actions. Versi
 requests and resolved once, in the Plan stage, before anything is built. Stable publication occurs only from a push to
 the configured default branch.
 
+With the default release-note settings, the pull request title becomes the release notes heading and its description
+becomes the release notes body. The release name remains the resolved version by default. Treat the selected label and
+the pull request content as the final decision about the release users receive; see
+[Writing release-note pull requests](writing-release-note-prs.md) for the required user-facing format.
+
 ## Flow
 
 1. Resolve settings and release intent.
diff --git a/docs/content/guides/writing-release-note-prs.md b/docs/content/guides/writing-release-note-prs.md
new file mode 100644
index 00000000..7c4639ce
--- /dev/null
+++ b/docs/content/guides/writing-release-note-prs.md
@@ -0,0 +1,148 @@
+---
+title: Writing release-note pull requests
+description: Turn a pull request into clear release notes that explain outcomes, adoption steps, and version impact.
+---
+
+# Writing release-note pull requests
+
+For the default Process-PSModule configuration, a pull request title becomes the GitHub Release notes heading and its
+description becomes the release notes body. The release name is the resolved version unless
+`Publish.Module.UsePRTitleAsReleaseName` changes that setting. Treat the title, description, and selected version label
+as the final decision about what users receive.
+
+This guide extends the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) with the release transition and
+adoption information required by Process-PSModule consumers. It applies to any releasable artifact: a PowerShell
+module, reusable workflow, GitHub Action, library, service, or infrastructure module.
+
+## Before starting
+
+- Identify the artifact and the people or systems that use it.
+- Inspect the configured version-label mapping and select the label that matches the delivered compatibility impact.
+  Do not assume a label name: repositories can configure their own mappings.
+- Find the latest published stable version and calculate the expected SemVer transition. If another release can merge
+  first, describe the semantic increment and re-check the numeric transition before the pull request is ready.
+- Identify every user-visible change and the steps an existing user needs to take to use it safely.
+
+## Steps
+
+1. Write the title in the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#title). Describe the
+   user-facing outcome, not the implementation activity.
+2. Open with one concise paragraph that says what users receive and why it matters. Use present tense and active voice.
+3. Group the changes by experience using `## New:`, `## Changed:`, `## Fixed:`, and, for an incompatible release,
+   `## Breaking Changes`. Each group explains the outcome before any implementation detail.
+4. Add `## Adopting this release` after the user-facing change groups. Give the steps in the order an existing user
+   takes them from the currently supported version, workflow reference, configuration, or invocation. State explicitly
+   when no configuration, code, or usage change is needed. This is normal release adoption, not a migration.
+5. Add `## Release impact`. State the configured label, the resulting SemVer effect, and the transition from the
+   current published version to the planned release version. Explain whether the numeric value is provisional because
+   it is resolved from the current published version at release time.
+6. Finish with the required `Technical details` and `Relevant issues (or links)` blocks from the
+   [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#description-structure). Technical details explain
+   how the outcome was delivered; they do not replace the user-facing narrative or adoption steps.
+
+## Release-note structure
+
+Use only the user-facing change headings that apply, but always include an adoption answer and release impact for a
+published change.
+
+````markdown
+<One paragraph explaining what users receive and why it matters.>
+
+## New: <capability>
+
+<What users can now do and the result they get.>
+
+## Changed: <existing behavior>
+
+<What users experience differently.>
+
+## Fixed: <problem>
+
+<What now works and how users benefit.>
+
+## Breaking Changes
+
+<What no longer works, who is affected, and the compatible replacement.>
+
+## Adopting this release
+
+1. <First action from the currently supported version or reference.>
+2. <Next action, configuration change, or verification step.>
+
+<Or: No configuration, code, or invocation change is required. Update to this version normally.>
+
+## Release impact
+
+- **Configured label:** `<label that selects this release>`
+- **SemVer change:** `<Major | Minor | Patch>`
+- **Version transition:** `<current published version> -> <planned release version>`
+- **Release name:** `<planned release version>`
+
+---
+<details>
+<summary>Technical details</summary>
+
+<Implementation approach, compatibility evidence, validation, and standards alignment.>
+
+</details>
+
+<details>
+<summary>Relevant issues (or links)</summary>
+
+- Resolves Owner/Repository#123
+
+### Related work
+
+- References Owner/Repository#456
+
+</details>
+````
+
+For `release:skip` or an equivalent configured label, replace the release-impact list with an explicit statement that
+no artifact is published and no version transition occurs. For a prerelease, state the selected bump and that the
+release is a validation channel rather than the latest stable version.
+
+## Writing the adoption path
+
+The adoption path is release-wide. It connects related changes into the sequence a user follows instead of leaving
+instructions scattered through feature sections.
+
+| Artifact users consume | Adoption path answers |
+| --- | --- |
+| PowerShell module | Which version to install, whether scripts or command usage change, and how to verify the updated behavior. |
+| Reusable workflow | Which `uses:` reference to change, which trigger, permission, input, secret, or label changes are required, and the order to apply them. |
+| GitHub Action | Which action reference and inputs change, whether permissions or secrets are affected, and how callers verify it. |
+| Library or service | Which dependency, API contract, setting, or deployment step changes and what compatibility behavior remains. |
+| Infrastructure module | Which module version and input or output contracts change, the safe rollout order, and any state or deployment action. |
+
+Do not label this section `Migration` unless the release performs a genuine data or platform migration. A routine
+version update, reference change, configuration adjustment, or command replacement belongs under
+`Adopting this release`.
+
+## Release impact
+
+The configured version label determines the next version by applying its SemVer bump to the current published
+version. The exact label can differ between repositories; describe its effect rather than relying on a conventional
+name. The title and body explain the user value, while the version becomes the default GitHub Release name.
+
+Before marking a pull request ready, refresh the current version and planned version if another release landed while
+the branch was open. Do not publish a stale numeric transition. A prerelease label selects a release channel alongside
+the version bump; it is not the bump itself.
+
+## Verify
+
+- The title and opening paragraph are understandable without internal file, function, or class names.
+- Every user-visible change says what the user gets, and the technical details remain in the final details block.
+- `Adopting this release` gives complete, ordered instructions for affected users or explicitly says no action is
+  needed.
+- The configured label, SemVer effect, current version, and planned version agree with the release configuration.
+- No placeholders or authoring comments remain in the release notes body.
+- The final details blocks match the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#description-structure).
+
+## If it fails
+
+| Symptom | Cause | Resolution |
+| --- | --- | --- |
+| The next version cannot be stated accurately. | Another release may change the published baseline, or the configured label is unknown. | State the semantic impact, inspect the configured label mapping, and refresh the numeric transition before review. |
+| A user cannot tell whether they need to change anything. | The change explanation describes implementation instead of adoption. | Add an ordered adoption path or explicitly state that normal updating is sufficient. |
+| The release notes read like reviewer notes. | Technical implementation details appear in the user-facing sections. | Move implementation, validation, and design detail to `Technical details`; retain the user outcome and action in the main body. |
diff --git a/docs/zensical.toml b/docs/zensical.toml
index 9c9dbd78..6a0d6a89 100644
--- a/docs/zensical.toml
+++ b/docs/zensical.toml
@@ -32,6 +32,7 @@ nav = [
     {"Writing module tests" = "guides/writing-module-tests.md"},
     {"Skipping framework tests" = "guides/skipping-framework-tests.md"},
     {"Versioning and releases" = "guides/versioning-and-releases.md"},
+    {"Writing release-note PRs" = "guides/writing-release-note-prs.md"},
     {"Validating before review" = "guides/validating-before-review.md"},
     {"Writing plugin skills" = "guides/writing-plugin-skills.md"},
     {"Module development orchestration" = "guides/module-development-orchestration.md"},

From 517607b996234b1608ea140127a8b3c4c9cfdd78 Mon Sep 17 00:00:00 2001
From: Marius Storhaug <marstor@hotmail.com>
Date: Sat, 5 Sep 2026 08:31:08 +0200
Subject: [PATCH 2/3] Add release note authoring skill

Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
---
 .github/PULL_REQUEST_TEMPLATE.md              | 61 +++++++++++++++++++
 .github/plugin/README.md                      |  4 ++
 .../psmodule-release-note-authoring/SKILL.md  | 37 +++++++++++
 3 files changed, 102 insertions(+)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000..7c3c8b4d
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,61 @@
+<!--
+This title and description become the GitHub Release notes by default. Write for the people who use the released
+artifact. See docs/content/guides/writing-release-note-prs.md and the psmodule-release-note-authoring skill.
+Delete headings that do not apply. Remove every placeholder and comment before marking the pull request ready.
+-->
+
+<One concise paragraph: what users receive and why it matters.>
+
+## New: <capability>
+
+<What users can now do and the result they get.>
+
+## Changed: <behavior>
+
+<What users experience differently.>
+
+## Fixed: <problem>
+
+<What now works and how users benefit.>
+
+## Breaking Changes
+
+<What no longer works, who is affected, and the compatible replacement.>
+
+## Adopting this release
+
+1. <First action from the currently supported version, reference, configuration, or invocation.>
+2. <Next action and how the user verifies the outcome.>
+
+<Or: No configuration, code, or invocation change is required. Update to this version normally.>
+
+## Release impact
+
+- **Configured label:** `<label that selects this release>`
+- **SemVer change:** `<Major | Minor | Patch>`
+- **Version transition:** `<current published version> -> <planned release version>`
+- **Release name:** `<planned release version>`
+
+<!--
+For a skip/no-release label, say that no artifact is published and no version transition occurs.
+For a prerelease, state the selected bump and that it is not the latest stable version.
+-->
+
+---
+<details>
+<summary>Technical details</summary>
+
+<Implementation approach, compatibility evidence, validation, and standards alignment.>
+
+</details>
+
+<details>
+<summary>Relevant issues (or links)</summary>
+
+- Resolves Owner/Repository#123
+
+### Related work
+
+- References Owner/Repository#456
+
+</details>
diff --git a/.github/plugin/README.md b/.github/plugin/README.md
index 81774b3e..2ee002a4 100644
--- a/.github/plugin/README.md
+++ b/.github/plugin/README.md
@@ -38,6 +38,10 @@ The
 [`psmodule-skill-authoring`](./psmodule/skills/psmodule-skill-authoring/SKILL.md)
 skill keeps plugin skills thin and points shared authoring guidance to the
 documentation site.
+The
+[`psmodule-release-note-authoring`](./psmodule/skills/psmodule-release-note-authoring/SKILL.md)
+skill writes release-bound pull requests as user-facing release notes with
+adoption steps and verified version transitions.
 Verify the installation with:
 
 ```console
diff --git a/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md b/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md
new file mode 100644
index 00000000..d79e36b2
--- /dev/null
+++ b/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: psmodule-release-note-authoring
+description: Write or review release-bound pull requests as user-facing release notes with adoption steps and a verified version transition.
+---
+
+# Author release-note pull requests
+
+Use this skill when authoring, rewriting, or reviewing a pull request whose title and description will be published as
+release notes. Read the [release-note pull request guide](../../../../../docs/content/guides/writing-release-note-prs.md)
+before editing the pull request. That guide owns the release-note structure and the user-facing writing rules.
+
+## Operating contract
+
+1. Identify the artifact users consume, its current published version or reference, its configured version-label
+   mapping, and the users affected by the change.
+2. Write the title and leading paragraph around the user outcome. Group changes by what users experience, not by files
+   or implementation activity.
+3. Include an ordered `Adopting this release` section for every affected user. State that normal updating is sufficient
+   when no configuration, code, or invocation change is required.
+4. Verify the configured label, SemVer effect, current published version, and planned release version together. Refresh
+   the numeric transition before the pull request is ready if another release may have changed the baseline.
+5. Put implementation, validation, compatibility evidence, and standards alignment in the final `Technical details`
+   block. Preserve the MSX `Relevant issues (or links)` block at the end.
+6. Rework the title, adoption path, and release impact whenever the diff, selected label, or compatibility impact
+   changes. Do not leave placeholders, stale version values, or reviewer-oriented prose in the published body.
+
+## Stop conditions
+
+Stop and report when the release label mapping, current published version, artifact consumer, or compatibility impact
+cannot be determined. Do not infer a version transition from conventional label names, describe routine adoption as a
+migration, or claim that no user action is needed without inspecting the delivered behavior.
+
+## References
+
+- [Writing release-note pull requests](../../../../../docs/content/guides/writing-release-note-prs.md)
+- [Versioning and releases](../../../../../docs/content/guides/versioning-and-releases.md)
+- [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/)

From 6a517c3f8e98c9de091860bdc32113c48752b24e Mon Sep 17 00:00:00 2001
From: Marius Storhaug <marstor@hotmail.com>
Date: Sat, 5 Sep 2026 08:42:27 +0200
Subject: [PATCH 3/3] Clarify release note PR control plan

Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
---
 .github/PULL_REQUEST_TEMPLATE.md              |  8 ++--
 .github/plugin/README.md                      |  4 +-
 .../psmodule-release-note-authoring/SKILL.md  | 15 ++++----
 .../guides/configuring-the-pipeline.md        |  2 +-
 ...-prs.md => formatting-release-note-prs.md} | 37 +++++++++++--------
 .../content/guides/versioning-and-releases.md |  2 +-
 docs/zensical.toml                            |  2 +-
 7 files changed, 40 insertions(+), 30 deletions(-)
 rename docs/content/guides/{writing-release-note-prs.md => formatting-release-note-prs.md} (81%)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 7c3c8b4d..2ca093f9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,7 +1,9 @@
 <!--
-This title and description become the GitHub Release notes by default. Write for the people who use the released
-artifact. See docs/content/guides/writing-release-note-prs.md and the psmodule-release-note-authoring skill.
-Delete headings that do not apply. Remove every placeholder and comment before marking the pull request ready.
+This is the final content-control plan for the pull request author. The automated release process reuses this title
+and description as the GitHub Release notes by default; it does not create a separate release-note document. Format
+the title, description, and selected version label for the people who use the released artifact. See
+docs/content/guides/formatting-release-note-prs.md and the psmodule-release-note-authoring skill. Delete headings
+that do not apply. Remove every placeholder and comment before marking the pull request ready.
 -->
 
 <One concise paragraph: what users receive and why it matters.>
diff --git a/.github/plugin/README.md b/.github/plugin/README.md
index 2ee002a4..544debb9 100644
--- a/.github/plugin/README.md
+++ b/.github/plugin/README.md
@@ -40,8 +40,8 @@ skill keeps plugin skills thin and points shared authoring guidance to the
 documentation site.
 The
 [`psmodule-release-note-authoring`](./psmodule/skills/psmodule-release-note-authoring/SKILL.md)
-skill writes release-bound pull requests as user-facing release notes with
-adoption steps and verified version transitions.
+skill formats pull request titles, descriptions, and labels as user-facing
+release notes with adoption steps and verified version transitions.
 Verify the installation with:
 
 ```console
diff --git a/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md b/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md
index d79e36b2..c4d6b50e 100644
--- a/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md
+++ b/.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md
@@ -1,20 +1,21 @@
 ---
 name: psmodule-release-note-authoring
-description: Write or review release-bound pull requests as user-facing release notes with adoption steps and a verified version transition.
+description: Format pull request titles, descriptions, and labels as user-facing release notes with adoption steps and a verified version transition.
 ---
 
-# Author release-note pull requests
+# Format release-note pull requests
 
-Use this skill when authoring, rewriting, or reviewing a pull request whose title and description will be published as
-release notes. Read the [release-note pull request guide](../../../../../docs/content/guides/writing-release-note-prs.md)
+Use this skill when formatting, rewriting, or reviewing a pull request whose title and description will be published
+as release notes. This skill controls the author-facing pull request message; it does not create separate release
+notes. Read the [pull-request formatting guide](../../../../../docs/content/guides/formatting-release-note-prs.md)
 before editing the pull request. That guide owns the release-note structure and the user-facing writing rules.
 
 ## Operating contract
 
 1. Identify the artifact users consume, its current published version or reference, its configured version-label
    mapping, and the users affected by the change.
-2. Write the title and leading paragraph around the user outcome. Group changes by what users experience, not by files
-   or implementation activity.
+2. Format the title, description, and selected label around one user outcome. Group description changes by what users
+   experience, not by files or implementation activity.
 3. Include an ordered `Adopting this release` section for every affected user. State that normal updating is sufficient
    when no configuration, code, or invocation change is required.
 4. Verify the configured label, SemVer effect, current published version, and planned release version together. Refresh
@@ -32,6 +33,6 @@ migration, or claim that no user action is needed without inspecting the deliver
 
 ## References
 
-- [Writing release-note pull requests](../../../../../docs/content/guides/writing-release-note-prs.md)
+- [Formatting release-note pull requests](../../../../../docs/content/guides/formatting-release-note-prs.md)
 - [Versioning and releases](../../../../../docs/content/guides/versioning-and-releases.md)
 - [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/)
diff --git a/docs/content/guides/configuring-the-pipeline.md b/docs/content/guides/configuring-the-pipeline.md
index dd7d9258..2987c76c 100644
--- a/docs/content/guides/configuring-the-pipeline.md
+++ b/docs/content/guides/configuring-the-pipeline.md
@@ -161,7 +161,7 @@ Commands can now authenticate in environments where a browser callback is unavai
 - **Version transition:** `v1.4.2` -> `v1.5.0`
 ```
 
-Use [Writing release-note pull requests](writing-release-note-prs.md) for the complete user-facing structure,
+Use [Formatting release-note pull requests](formatting-release-note-prs.md) for the complete user-facing structure,
 including technical details and relevant issue links.
 
 ### Version-only release names
diff --git a/docs/content/guides/writing-release-note-prs.md b/docs/content/guides/formatting-release-note-prs.md
similarity index 81%
rename from docs/content/guides/writing-release-note-prs.md
rename to docs/content/guides/formatting-release-note-prs.md
index 7c4639ce..26e27b31 100644
--- a/docs/content/guides/writing-release-note-prs.md
+++ b/docs/content/guides/formatting-release-note-prs.md
@@ -1,17 +1,21 @@
 ---
-title: Writing release-note pull requests
-description: Turn a pull request into clear release notes that explain outcomes, adoption steps, and version impact.
+title: Formatting release-note pull requests
+description: Control the title, description, and label that automated releases reuse as user-facing release notes.
 ---
 
-# Writing release-note pull requests
+# Formatting release-note pull requests
 
-For the default Process-PSModule configuration, a pull request title becomes the GitHub Release notes heading and its
-description becomes the release notes body. The release name is the resolved version unless
-`Publish.Module.UsePRTitleAsReleaseName` changes that setting. Treat the title, description, and selected version label
-as the final decision about what users receive.
+This guide is the final content-control plan for an author formatting a pull request. It is not release notes for a
+specific change. It defines how the pull request title, description, and version label communicate what users receive
+when the automated release process reuses them.
 
-This guide extends the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) with the release transition and
-adoption information required by Process-PSModule consumers. It applies to any releasable artifact: a PowerShell
+With the default Process-PSModule settings, automation reuses the pull request title as the release notes heading and
+the description as the release notes body. The release name is the resolved version unless
+`Publish.Module.UsePRTitleAsReleaseName` changes that setting. The author, rather than the automation, makes the final
+message decision by formatting those three pull request fields before review.
+
+This guide extends the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) with the release transition
+and adoption information required by Process-PSModule consumers. It applies to any releasable artifact: a PowerShell
 module, reusable workflow, GitHub Action, library, service, or infrastructure module.
 
 ## Before starting
@@ -25,7 +29,7 @@ module, reusable workflow, GitHub Action, library, service, or infrastructure mo
 
 ## Steps
 
-1. Write the title in the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#title). Describe the
+1. Format the title in the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#title). Describe the
    user-facing outcome, not the implementation activity.
 2. Open with one concise paragraph that says what users receive and why it matters. Use present tense and active voice.
 3. Group the changes by experience using `## New:`, `## Changed:`, `## Fixed:`, and, for an incompatible release,
@@ -40,10 +44,11 @@ module, reusable workflow, GitHub Action, library, service, or infrastructure mo
    [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#description-structure). Technical details explain
    how the outcome was delivered; they do not replace the user-facing narrative or adoption steps.
 
-## Release-note structure
+## Pull-request description structure
 
 Use only the user-facing change headings that apply, but always include an adoption answer and release impact for a
-published change.
+published change. This is the format of the pull-request description that the release process later reuses; it is not
+a separate release-note document to maintain.
 
 ````markdown
 <One paragraph explaining what users receive and why it matters.>
@@ -119,11 +124,12 @@ Do not label this section `Migration` unless the release performs a genuine data
 version update, reference change, configuration adjustment, or command replacement belongs under
 `Adopting this release`.
 
-## Release impact
+## Formatting release impact
 
 The configured version label determines the next version by applying its SemVer bump to the current published
 version. The exact label can differ between repositories; describe its effect rather than relying on a conventional
-name. The title and body explain the user value, while the version becomes the default GitHub Release name.
+name. The pull-request title and description explain the user value, while the version becomes the default GitHub
+Release name.
 
 Before marking a pull request ready, refresh the current version and planned version if another release landed while
 the branch was open. Do not publish a stale numeric transition. A prerelease label selects a release channel alongside
@@ -131,7 +137,8 @@ the version bump; it is not the bump itself.
 
 ## Verify
 
-- The title and opening paragraph are understandable without internal file, function, or class names.
+- The title, description, and selected label are understandable as one user-facing message without internal file,
+  function, or class names.
 - Every user-visible change says what the user gets, and the technical details remain in the final details block.
 - `Adopting this release` gives complete, ordered instructions for affected users or explicitly says no action is
   needed.
diff --git a/docs/content/guides/versioning-and-releases.md b/docs/content/guides/versioning-and-releases.md
index c7be84c0..864e037d 100644
--- a/docs/content/guides/versioning-and-releases.md
+++ b/docs/content/guides/versioning-and-releases.md
@@ -12,7 +12,7 @@ the configured default branch.
 With the default release-note settings, the pull request title becomes the release notes heading and its description
 becomes the release notes body. The release name remains the resolved version by default. Treat the selected label and
 the pull request content as the final decision about the release users receive; see
-[Writing release-note pull requests](writing-release-note-prs.md) for the required user-facing format.
+[Formatting release-note pull requests](formatting-release-note-prs.md) for the required user-facing format.
 
 ## Flow
 
diff --git a/docs/zensical.toml b/docs/zensical.toml
index 6a0d6a89..9cc0eafb 100644
--- a/docs/zensical.toml
+++ b/docs/zensical.toml
@@ -32,7 +32,7 @@ nav = [
     {"Writing module tests" = "guides/writing-module-tests.md"},
     {"Skipping framework tests" = "guides/skipping-framework-tests.md"},
     {"Versioning and releases" = "guides/versioning-and-releases.md"},
-    {"Writing release-note PRs" = "guides/writing-release-note-prs.md"},
+    {"Formatting release-note PRs" = "guides/formatting-release-note-prs.md"},
     {"Validating before review" = "guides/validating-before-review.md"},
     {"Writing plugin skills" = "guides/writing-plugin-skills.md"},
     {"Module development orchestration" = "guides/module-development-orchestration.md"},