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. Suggested YAML validation was not run because Ruby is unavailable; no YAML changed.

Verified documentation tree: 1c99d4d38d64fc7c6e39f180d46f0804b6b51193.

[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:50 PM ET / 19:50 UTC.

ClawSweeper review

What this changes

The PR template puts plain-language user impact before implementation rationale while keeping compatibility requirements and evidence summaries visible.

Merge readiness

⛔ Blocked before merge - 1 item remains

This remains a useful, focused contribution: current main lacks the revised guidance, and no blocking defect was found.

Priority: P3
Reviewed head: 1c99d4d38d64fc7c6e39f180d46f0804b6b51193

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused documentation improvement with preserved requirements, passing supplied checks, and no actionable defect. 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 exemption applies to this template-only PR; source inspection and reported wording checks cover the changed prompts, with no production runtime behavior to exercise.
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 exemption applies to this template-only PR; source inspection and reported wording checks cover the changed prompts, with no production runtime behavior to exercise.
Evidence reviewed	9 items	Full applicable policy inspected: Read the complete root AGENTS.md and checked for nested policies and maintainer notes; none were found for the changed path. The template preserves the repository-specific compatibility, validation, and release-note guidance. Complete introduced change inspected: The pinned base-to-head diff changes only template headings and explanatory comments: 19 additions and 17 deletions. All four heading names, evidence checklist items, title conventions, and generated-file reminders remain present. The whitespace check passed and the working tree remained clean. Still absent from current main and latest release: Current main retains rationale before user impact and the longer prescribed opening. The v0.1.1 template also retains that earlier wording; the requested refinement is not already implemented.
Findings	None	None.
Security	None	None.

How this fits together

The repository’s PR template guides contributors as they write descriptions for router changes. Its prompts help reviewers understand the problem, consumer impact, tradeoffs, and validation.

flowchart LR
  A[Contributor opens a PR] --> B[Description template]
  B --> C[Problem and user impact]
  B --> D[Rationale and evidence]
  C --> E[Maintainer review]
  D --> E

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 exemption applies to this template-only PR; source inspection and reported wording checks cover the changed prompts, with no production runtime behavior to exercise.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep the concise problem-and-impact ordering together with visible compatibility obligations and a useful validation summary.

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

Not applicable: this changes contribution guidance rather than fixing a runtime defect; the complete before-and-after template is directly inspectable.

Is this the best way to solve the issue?

Yes: editing the existing template is the narrowest solution, and the patch retains its repository-specific obligations without introducing a competing template.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This is a low-risk contribution-template wording improvement with no runtime or package 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 exemption applies to this template-only PR; source inspection and reported wording checks cover the changed prompts, with no production runtime behavior to exercise.

Label justifications:

• P3: This is a low-risk contribution-template wording improvement with no runtime or package 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 exemption applies to this template-only PR; source inspection and reported wording checks cover the changed prompts, with no production runtime behavior to exercise.

Evidence

What I checked:

• Full applicable policy inspected: Read the complete root AGENTS.md and checked for nested policies and maintainer notes; none were found for the changed path. The template preserves the repository-specific compatibility, validation, and release-note guidance. (AGENTS.md:125, 1c99d4d38d64)
• Complete introduced change inspected: The pinned base-to-head diff changes only template headings and explanatory comments: 19 additions and 17 deletions. All four heading names, evidence checklist items, title conventions, and generated-file reminders remain present. The whitespace check passed and the working tree remained clean. (.github/PULL_REQUEST_TEMPLATE.md:6, 1c99d4d38d64)
• Still absent from current main and latest release: Current main retains rationale before user impact and the longer prescribed opening. The v0.1.1 template also retains that earlier wording; the requested refinement is not already implemented. (.github/PULL_REQUEST_TEMPLATE.md:15, ea06377b0e80)
• Release template checked: Direct inspection of the latest release tag confirms the previous description structure. (.github/PULL_REQUEST_TEMPLATE.md:15, f5ce7c0d7c04)
• Template history and routing: GitHub’s path history at pinned main identifies shakkernerd on the template’s prior commit. The commit endpoint reports the file as added. Local follow-history inspection encountered an unavailable historical object, so routing uses GitHub metadata without claiming host-verified source-line introduction. (.github/PULL_REQUEST_TEMPLATE.md, a2c881708ede)
• Linked wording precedent: The linked docs: make PR descriptions plain-language first openclaw#146253 is merged and describes the same plain-language ordering principle. It is a wording precedent, not a runtime dependency or evidence that this target repository already contains the change.

Likely related people:

• shakkernerd: 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.