Clarify release note PR control plan

Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.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.>

.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

.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/)

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

…ntent/guides/writing-release-note-prs.md …nt/guides/formatting-release-note-prs.mddocs/content/guides/writing-release-note-prs.md renamed to docs/content/guides/formatting-release-note-prs.md docs/content/guides/writing-release-note-prs.md renamed to 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,19 +124,21 @@ 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
 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.

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
 

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"},