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 while keeping important risks, required actions, and evidence visible.

Evidence

The template matches the reviewed core wording exactly. Heading, marker, preservation, and whitespace checks passed. Only the PR template changed.

Verified documentation tree: 5c87d3d4a91e437804db96ee9e9c657bee926710.

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

ClawSweeper review

What this changes

Updates the pull request template to put plain-language problems and user impact first while keeping risks, required actions, and evidence summaries visible.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: community’s current main still has the older template. This focused update follows the established cross-repository alignment direction and has no blocking findings.

Priority: P3
Reviewed head: 5c87d3d4a91e437804db96ee9e9c657bee926710

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused, consistent documentation update with verified source alignment and no actionable defects. 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: This automated-account PR changes only contributor template prose; the bot-authored exemption applies, and source inspection confirms the canonical wording match.
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: This automated-account PR changes only contributor template prose; the bot-authored exemption applies, and source inspection confirms the canonical wording match.
Evidence reviewed	6 items	Applicable repository policy: Read the complete root AGENTS.md and inventoried hidden files; no nested AGENTS.md or maintainer-notes directory was present. Mermaid guidance applies; README synchronization is not triggered. Complete introduced change: The pinned base-to-head diff changes only the PR template. All four section names remain; user impact moves before rationale, instructions favor concise explanations, and the maintainer-edit reminder remains in the source comment. Current main and related work: GitHub confirmed main remains at 83cd606 and this PR remains open. The open-PR listing returned no replacement. Merged #17 established alignment with the canonical core template but contains the older wording. No local release tags were present.
Findings	None	None.
Security	None	None.

How this fits together

The community repository’s pull request template guides contributors when drafting submissions on GitHub. Its prompts shape the explanations and validation evidence reviewers receive.

flowchart LR
  A[Contributor opens pull request] --> B[Community PR 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: This automated-account PR changes only contributor template prose; the bot-authored exemption applies, and source inspection confirms the canonical wording match.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep the community template aligned with the reviewed core wording, with concise explanations and visible material risks and evidence.

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

Not applicable: this changes documentation prompts rather than repairing a runtime defect; the complete template and introduced diff were inspected.

Is this the best way to solve the issue?

Yes: updating the existing template preserves the established submission structure and exactly matches the linked, merged core wording.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This is a focused contributor-documentation improvement with no runtime changes.
• 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: This automated-account PR changes only contributor template prose; the bot-authored exemption applies, and source inspection confirms the canonical wording match.

Label justifications:

• P3: This is a focused contributor-documentation improvement with no runtime changes.
• 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: This automated-account PR changes only contributor template prose; the bot-authored exemption applies, and source inspection confirms the canonical wording match.

Evidence

What I checked:

• Applicable repository policy: Read the complete root AGENTS.md and inventoried hidden files; no nested AGENTS.md or maintainer-notes directory was present. Mermaid guidance applies; README synchronization is not triggered. (AGENTS.md:1, 5c87d3d4a91e)
• Complete introduced change: The pinned base-to-head diff changes only the PR template. All four section names remain; user impact moves before rationale, instructions favor concise explanations, and the maintainer-edit reminder remains in the source comment. (.github/pull_request_template.md:17, 5c87d3d4a91e)
• Current main and related work: GitHub confirmed main remains at 83cd606 and this PR remains open. The open-PR listing returned no replacement. Merged chore: align pull request template #17 established alignment with the canonical core template but contains the older wording. No local release tags were present. (.github/pull_request_template.md, 83cd606cdfe0)
• Verified canonical wording: The linked docs: make PR descriptions plain-language first openclaw#146253 is merged. Its template was read fully and has blob 307a73b6b55a0888a7f6929b78f6041caea027da, identical to this branch. This supports the stated wording alignment, not closure in the separate community repository. (.github/pull_request_template.md:21, d23730ee7c54)
• Template history and routing: Follow-history and blame identify the prior template-alignment commit. Inspection of its raw recorded parent and the parent-to-commit diff confirms the template was added there; GitHub identifies hannesrudolph as the author of the corresponding merged PR. (.github/pull_request_template.md:7, 800e3752d3ee)
• Bot authorship and proof scope: The roboclaw-bot profile describes an automated account, supporting the bot-authored proof exemption. The captured PR body reports wording, heading, preservation, and whitespace checks; those are documentation validation, not runtime proof.

Likely related people:

• Hannes Rudolph: Raw commit 800e375 adds .github/pull_request_template.md:7 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 800e3752d3ee; files: .github/pull_request_template.md)

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.