docs: make PR descriptions plain-language first

[roboclaw-bot]

What Problem This Solves

PR authors need clearer guidance to explain the problem and outcome without a long technical introduction.

User Impact

User impact: contributors are prompted to put the concrete outcome first and keep risks, migrations, required actions, and useful evidence visible. No product behavior changes.

Why This Change Was Made

Carry over the approved wording from openclaw/openclaw#146253 while preserving the existing section names and maintainer-edit requirement.

Evidence

• Compared the live template with the original; no repository-specific additions were lost.
• Checked the replacement against the approved template, reviewed the diff, and ran git diff --check successfully.
• Reviewed repository guidance and PR workflows. Runtime tests were not run for this template-only change.

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

ClawSweeper review

What this changes

The PR shortens contributor guidance, places user impact before implementation rationale, and asks authors to keep risks and evidence summaries visible.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: this is a focused, useful template improvement that is absent from current main. No actionable correctness or security defects were found.

Priority: P3
Reviewed head: 6413529432f3d7e1f96439dce158d71e273bb039

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused, maintainable documentation patch with appropriate static validation and no identified 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: The bot-authored exemption applies to this PR-template wording change; source inspection and whitespace validation support the review without implying a live GitHub rendering test.
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 PR-template wording change; source inspection and whitespace validation support the review without implying a live GitHub rendering test.
Evidence reviewed	6 items	Introduced change and validation: The complete pinned diff changes only the PR template, retains all four heading names, and keeps the maintainer-edit instruction in the author-visible HTML comment. The separate read-only git diff --check completed successfully. Current main still has the earlier guidance: The live main endpoint still identifies the pinned base. Its template puts rationale before impact and lacks the new concise wording and explicit evidence-summary guidance; this change is not already implemented there. Template ownership and related work: GitHub file history identifies the template addition in this commit, and #36 confirms the earlier merged template work by hannesrudolph. The bounded PR listing found that earlier template PR and this proposal. Local follow-history encountered an unavailable promised object; GitHub commit and PR reads supplied the relevant history instead.
Findings	None	None.
Security	None	None.

How this fits together

This repository stores OpenClaw design proposals. Its GitHub PR template guides contributors from describing a problem through explaining impact, rationale, and validation for reviewers.

flowchart LR
  A[Contributor opens PR] --> B[PR description template]
  B --> C[Problem and user impact]
  B --> D[Rationale and evidence]
  C --> E[Reviewer assessment]
  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 PR-template wording change; source inspection and whitespace validation support the review without implying a live GitHub rendering test.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Use the shorter template to foreground outcomes while retaining explicit risk, required-action, and validation guidance.

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

Not applicable: this changes PR authoring guidance and does not report a runtime defect.

Is this the best way to solve the issue?

Yes: editing the existing template is a narrow solution, and the patch preserves its section names and contribution requirements.

AGENTS.md: not found in the target repository.

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

Labels

Label changes:

• add P3: This is contributor-facing documentation polish with no runtime or workflow execution 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: The bot-authored exemption applies to this PR-template wording change; source inspection and whitespace validation support the review without implying a live GitHub rendering test.

Label justifications:

• P3: This is contributor-facing documentation polish with no runtime or workflow execution 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: The bot-authored exemption applies to this PR-template wording change; source inspection and whitespace validation support the review without implying a live GitHub rendering test.

Evidence

What I checked:

• Introduced change and validation: The complete pinned diff changes only the PR template, retains all four heading names, and keeps the maintainer-edit instruction in the author-visible HTML comment. The separate read-only git diff --check completed successfully. (.github/pull_request_template.md:17, 6413529432f3)
• Current main still has the earlier guidance: The live main endpoint still identifies the pinned base. Its template puts rationale before impact and lacks the new concise wording and explicit evidence-summary guidance; this change is not already implemented there. (.github/pull_request_template.md:40, 967d9aac7472)
• Template ownership and related work: GitHub file history identifies the template addition in this commit, and chore: align pull request template #36 confirms the earlier merged template work by hannesrudolph. The bounded PR listing found that earlier template PR and this proposal. Local follow-history encountered an unavailable promised object; GitHub commit and PR reads supplied the relevant history instead. (.github/pull_request_template.md:11, 4b76d31d30ec)
• Linked wording precedent: The proposal explicitly carries wording from docs: make PR descriptions plain-language first openclaw#146253. GitHub confirms that PR is merged. It supports the stated direction but cannot establish implementation in the RFC repository.
• Automation author and proof scope: The author account roboclaw-bot identifies itself as automated. The bot-authored proof exemption applies to this template wording change; the body reports comparison and whitespace checks, without claiming runtime execution.
• Repository policy and subsystem boundary: Read README.md and the full template and inspected tracked paths and the dispatch workflow. No root or applicable nested AGENTS.md, maintainer notes, or local template-heading parser was found. The workflow is unchanged. (README.md:5, 6413529432f3)

Likely related people:

• Hannes Rudolph: Raw commit 4b76d31 adds .github/pull_request_template.md:11 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 4b76d31d30ec; 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.