From 40afe12ab1ed4db4740ead70b3d5baf1bc35ad7d Mon Sep 17 00:00:00 2001
From: roboclaw-bot <309084314+roboclaw-bot@users.noreply.github.com>
Date: Sat, 12 Sep 2026 19:40:57 +0000
Subject: [PATCH] docs: make PR descriptions plain-language first

Co-authored-by: hannesrudolph <49103247+hannesrudolph@users.noreply.github.com>
---
 .github/pull_request_template.md | 36 ++++++++++++++++----------------
 CONTRIBUTING.md                  |  5 +++--
 2 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index b79ac3e6..08e9180f 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -13,10 +13,6 @@ For fixes, describe the user-visible symptom and trigger:
 fix: launcher exits without a diagnostic when Node is missing
 Avoid implementation details such as:
 fix: add null check to payload resolver
--->
-
-<details>
-<summary>Additional instructions</summary>
 
 **MUST:** Keep **Allow edits from maintainers** enabled for this PR so
 maintainers can help update the branch when needed.
@@ -24,37 +20,39 @@ maintainers can help update the branch when needed.
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for the validation commands this
 repository expects and for the packaging, signing, and NativeAOT rules that
 apply to launcher changes.
-
-</details>
+-->
 
 ## What Problem This Solves
 
 <!--
 Describe the concrete user, contributor, security, or operational problem.
-For fixes, begin with:
-"Fixes an issue where users <do X> would <experience Y> when <condition>."
+Use one short, plain-language sentence. For fixes, prefer:
+"Fixes: <what goes wrong> when <trigger or condition>."
+For other changes, describe the need without inventing a bug.
 
 Name the affected surface: the `openclaw.exe` launcher, packaged application,
 MSIX composition, the signing policy, or the GitHub Actions workflow. Do not
 describe the code-level cause here.
 -->
 
-## Why This Change Was Made
+## User Impact
 
 <!--
-In one or two sentences, explain the complete shipped solution, key design
-decisions, and relevant boundaries or non-goals. Include implementation detail
-only when it helps reviewers understand user-visible behavior or risk.
-Avoid file-by-file narration.
+"User impact: <what users, operators, or contributors can now do or expect>."
+Lead with the concrete outcome in plain language, usually one sentence.
+For internal-only changes, say there is no user-visible change; do not invent a benefit.
+Keep important risks, breaking changes, migrations, and required user actions visible here.
+For tooling or policy changes, describe any actual contributor or reliability
+benefit without claiming a user-visible behavior change.
 -->
 
-## User Impact
+## Why This Change Was Made
 
 <!--
-State what users, operators, or contributors can now do or expect. Lead with
-the concrete benefit. If there is no user-visible behavior change - which is
-normal for tooling and policy changes - say so plainly and name the
-contributor or reliability benefit instead.
+Briefly explain how the change addresses the problem without repeating the impact.
+Keep the body short. Leave file lists, internal acronyms, and root-cause walkthroughs
+in the diff or optional <details>; include technical detail only when it explains
+behavior or a material tradeoff. Do not hide risks or required actions in <details>.
 -->
 
 ## Evidence
@@ -73,4 +71,6 @@ Include CI links, artifact links, redacted logs, or terminal output. State
 which lanes you did not run and why. Reviewers will inspect the code, tests,
 and CI; use this section to make validation easy to understand rather than to
 restate the diff.
+Summarize what was checked and the result; note meaningful gaps. Link long output
+or put it in optional <details>, keeping the useful evidence summary visible.
 -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c6549aca..52b218bf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -203,8 +203,9 @@ Use the pull request template. Title the PR
 `improve`, `refactor`, `docs`, or `chore`. Describe the outcome rather than the
 mechanism.
 
-Every PR body should explain the problem it solves, why the change was made,
-the user or contributor impact, and the evidence that it works. Name the exact
+Lead with the problem and user or contributor impact in short, plain-language
+sentences, followed by a brief explanation and useful evidence. Keep technical
+details optional, but important risks and required actions visible. Name the exact
 head SHA your evidence came from and state which validation lanes you did not
 run.