From 321c05680f7c94585c76aba61cea28397ca18dc5 Mon Sep 17 00:00:00 2001
From: roboclaw-bot <309084314+roboclaw-bot@users.noreply.github.com>
Date: Sat, 12 Sep 2026 19:37: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 | 38 ++++++++++++++------------------
 1 file changed, 17 insertions(+), 21 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index e902c47..307a73b 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -13,43 +13,37 @@ For fixes, describe the user-visible symptom and trigger:
 fix: task list fails to load when user has no environments
 Avoid implementation details such as:
 fix: add null check to task query
--->
-
-<details>
-<summary>Additional instructions</summary>
 
 **MUST:** Keep **Allow edits from maintainers** enabled for this PR so maintainers
 can help update the branch when needed.
-
-</details>
+-->
 
 ## What Problem This Solves
 
 <!--
 Describe the concrete user, product, or operational problem.
-For fixes, begin with:
-"Fixes an issue where users <do X> would <experience Y> when <condition>."
-or:
-"Resolves a problem where..."
-
-Name the affected UI surface or workflow. Do not describe the code-level cause here.
+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 workflow, not the code-level cause.
 -->
 
-## 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 developers 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.
 -->
 
-## User Impact
+## Why This Change Was Made
 
 <!--
-State what users, operators, or developers can now do or expect. Lead with the
-concrete benefit and use user-facing language. If there is no user-visible
-impact, say so plainly.
+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
@@ -62,4 +56,6 @@ changes when it clarifies the result.
 
 Reviewers will inspect the code, tests, and CI. Use this section to make the
 validation easy to understand, not 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.
 -->