docs: make PR descriptions plain-language first

[roboclaw-bot]

What Problem This Solves

Contributors need a shorter, clearer way to explain their changes before implementation details.

User Impact

User impact: contributors are prompted to state the problem and concrete outcome first. No product behavior changes or migration steps.

Why This Change Was Made

Applies the plain-language template from openclaw/openclaw#146253 while preserving section names, maintainer edits, and evidence requirements.

Evidence

• Compared the live template with the original and the approved replacement; reviewed local contribution and authoring rules.
• git diff --check passed; only the PR template changed. No runtime tests run for this documentation-only change.
• AI-assisted; manually reviewed the wording and scope.

[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.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clawhub	Ready	Preview	Sep 12, 2026 7:42pm UTC

[blacksmith-sh]

Found 2 test failures on Blacksmith runners:

Failures

Test	View Logs
[chromium] › e2e/ public-routes-smoke.pw.test.ts:239:3 › public route renders: plugins browse ──	View Logs
e2e/public-routes-smoke.pw.test.ts/public route renders: plugins browse	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[clawsweeper]

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

ClawSweeper review

What this changes

The PR shortens contributor prompts, 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 documentation improvement that is not yet on ClawHub main. No blocking findings.

Priority: P3
Reviewed head: 3c59bc40d2c60801770961505b588cfc29d44dc9

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused, coherent template improvement with preserved section names and evidence guidance, and no blocking 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 bot-authored template-only change has no production runtime path or material authority change; source review and the reported wording checks cover its editorial scope.
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 bot-authored template-only change has no production runtime path or material authority change; source review and the reported wording checks cover its editorial scope.
Evidence reviewed	7 items	Complete introduced change: The pinned diff changes only the PR template: all four section names and evidence examples remain, user impact moves earlier, and the maintainer-edit reminder moves into the editor-visible HTML comment. Current main still uses the previous template: The main template retains the longer prompts and places implementation rationale before user impact. The live main endpoint confirmed the supplied main SHA. Latest release comparison: The supplied v0.23.3 release commit also contains the previous wording and section order.
Findings	None	None.
Security	None	None.

How this fits together

ClawHub’s GitHub PR template guides contributors when writing a proposed change’s description. Its prompts turn contributor context into problem, impact, rationale, and evidence sections for reviewers.

flowchart LR
  A[Contributor opens PR] --> B[PR 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: This bot-authored template-only change has no production runtime path or material authority change; source review and the reported wording checks cover its editorial scope.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
LOC	+17/-21 (1 file)	The change is limited to contributor-facing template text.

Technical review

Best possible solution:

Keep concise problem-and-impact prompts in the existing template while preserving visible risk summaries and meaningful validation evidence.

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

Not applicable: this changes editorial guidance rather than repairing a runtime defect; the complete template diff establishes the behavior being changed.

Is this the best way to solve the issue?

Yes. Editing the existing template is the best location because contributors encounter it while drafting; expanding CONTRIBUTING.md would add a separate reading step and duplicate guidance.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This improves contributor writing guidance without changing product behavior.
• 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 bot-authored template-only change has no production runtime path or material authority change; source review and the reported wording checks cover its editorial scope.

Label justifications:

• P3: This improves contributor writing guidance without changing product behavior.
• 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 bot-authored template-only change has no production runtime path or material authority change; source review and the reported wording checks cover its editorial scope.

Evidence

What I checked:

• Complete introduced change: The pinned diff changes only the PR template: all four section names and evidence examples remain, user impact moves earlier, and the maintainer-edit reminder moves into the editor-visible HTML comment. (.github/pull_request_template.md:17, 3c59bc40d2c6)
• Current main still uses the previous template: The main template retains the longer prompts and places implementation rationale before user impact. The live main endpoint confirmed the supplied main SHA. (.github/pull_request_template.md:39, 8c2de6c506bb)
• Latest release comparison: The supplied v0.23.3 release commit also contains the previous wording and section order. (.github/pull_request_template.md:39, 87ca030c30f3)
• Prior template work and routing: File history identified the earlier template alignment, and GitHub verified chore: align pull request template #3077 as merged and authored by hannesrudolph. Local blame and patch inspection encountered an unavailable historical object; the GitHub commit endpoint supplied the historical patch instead. (.github/pull_request_template.md, 05a798c4ba91)
• Linked wording precedent: The PR explicitly adapts docs: make PR descriptions plain-language first openclaw#146253; GitHub confirms that change is merged. This is editorial precedent in another repository, not a merged ClawHub replacement or a runtime dependency.
• Validation and policy: Read the complete root AGENTS.md and CONTRIBUTING.md; no applicable nested AGENTS.md or maintainer-notes directory was found. The whitespace check passed, and the final working-tree status was clean. No builds, tests, or target review helpers were executed. (AGENTS.md, 3c59bc40d2c6)

Likely related people:

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