docs: make PR descriptions plain-language first

[roboclaw-bot]

Related: openclaw/openclaw#146253

What Problem This Solves

Fixes: PR descriptions bury the problem and user impact in technical detail.

User Impact

Contributors get clearer prompts to explain what changes in plain English. No runtime behavior changes.

Why This Change Was Made

Applies the merged plain-English template improvement while preserving this repository’s validation, security, and compatibility requirements.

Evidence

Checked heading order and preservation of repository-specific sections and evidence checklists. Markdown formatting, whitespace checks, and independent wording review passed. Runtime and package suites were not run for this wording-only change.

Verified documentation tree: 40afe12ab1ed4db4740ead70b3d5baf1bc35ad7d.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 12, 2026, 3:53 PM ET / 19:53 UTC.

ClawSweeper review

What this changes

Updates the PR template and contributor guide to put plain-language problem and impact statements first while keeping risks, required actions, and validation evidence visible.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: this focused documentation improvement is not on main, and no actionable defect was found. The related upstream change supports the approach but does not supersede this repository’s PR.

Priority: P3
Reviewed head: 40afe12ab1ed4db4740ead70b3d5baf1bc35ad7d

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused, consistent documentation change with preserved repository requirements and no actionable findings. Real behavior proof remains required by host policy.
Proof confidence	🌊 off-meta tidepool	Recorded reviewer rating; Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: The bot-authored change only edits contributor instructions; its body identifies the reviewed revision and wording checks, and no production execution path changes.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Required by policy	Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: The bot-authored change only edits contributor instructions; its body identifies the reviewed revision and wording checks, and no production execution path changes.
Evidence reviewed	7 items	Complete introduced change: The verified base-to-head diff changes only the PR template and contribution guide; validation commands, exact evidence revision requirements, and release-owned changelog guidance remain intact. Main retains the previous template: Main still places the explanation before user impact and uses the older prompts. The supplied latest release points to this same main revision; this PR’s wording is not present there. Whitespace validation: The introduced diff passes the read-only whitespace check. No build or runtime tests were executed for this prose-only change.
Findings	None	None.
Security	None	None.

How this fits together

This repository packages OpenClaw for Windows. Its contribution guide and GitHub PR template guide contributors in explaining changes and supplying evidence for reviewers.

flowchart LR
 A[Contributor opens PR] --> B[PR template]
 C[Contribution guide] --> B
 B --> D[Problem and impact]
 B --> E[Explanation and evidence]
 D --> F[Maintainer review]
 E --> F

Loading

Before merge

• Add real behavior proof - Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: The bot-authored change only edits contributor instructions; its body identifies the reviewed revision and wording checks, and no production execution path changes.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Use concise problem-first descriptions while preserving visible compatibility risks, required actions, and evidence summaries.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this changes editorial guidance rather than repairing a runtime defect; the old and proposed wording were compared directly.

Is this the best way to solve the issue?

Yes: editing the existing template and contribution guide is a narrow, consistent way to improve descriptions without introducing competing guidance or weakening validation requirements.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 735bd4e27ff5.

Labels

Label changes:

• add P3: This is contributor-facing documentation polish with no runtime or packaging behavior change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit. This is the recorded reviewer rating; real behavior proof remains required by host policy.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: The bot-authored change only edits contributor instructions; its body identifies the reviewed revision and wording checks, and no production execution path changes.

Label justifications:

• P3: This is contributor-facing documentation polish with no runtime or packaging behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit. This is the recorded reviewer rating; real behavior proof remains required by host policy.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Required by policy: the recorded not-applicable assessment does not satisfy the current PR proof policy. Put relevant after-change evidence in the main PR body, then request a fresh review with @clawsweeper re-review. Recorded reviewer context: The bot-authored change only edits contributor instructions; its body identifies the reviewed revision and wording checks, and no production execution path changes.

Evidence

What I checked:

• Complete introduced change: The verified base-to-head diff changes only the PR template and contribution guide; validation commands, exact evidence revision requirements, and release-owned changelog guidance remain intact. (.github/pull_request_template.md:25, 40afe12ab1ed)
• Main retains the previous template: Main still places the explanation before user impact and uses the older prompts. The supplied latest release points to this same main revision; this PR’s wording is not present there. (.github/pull_request_template.md:42, 735bd4e27ff5)
• Whitespace validation: The introduced diff passes the read-only whitespace check. No build or runtime tests were executed for this prose-only change. (40afe12ab1ed)
• Related merged wording change: The body links docs: make PR descriptions plain-language first openclaw#146253, which GitHub confirms merged on 2026-09-12. It establishes the editorial precedent, not implementation in the target repository or a dependency runtime contract.
• Contribution-guidance history: GitHub verifies paulcam206 authored the merged contribution-guidance work at chore: introduce non-blocking .NET quality analysis #16. Local log and raw commit inspection support routing to this area contributor. Older file-history traversal and blame encountered unavailable objects, so no source-line introduction attribution is asserted. (CONTRIBUTING.md, df59c5151629)
• Recent guidance contributor: The merged docs: align guidance with immutable package execution #27 was authored by xlinush; its related source change updates both touched documents for immutable package execution. (.github/pull_request_template.md:33, 52f2a53fb62b)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• xlinush: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.