docs: make PR descriptions plain-language first

[roboclaw-bot]

Related: openclaw/openclaw#146253

What Problem This Solves

PR authors need clearer prompts to explain the problem and outcome before technical detail.

User Impact

User impact: Contributors are prompted to write short, plain-language descriptions while keeping risks, required actions, and evidence visible. No runtime changes or migrations.

Why This Change Was Made

Carry the approved core template into hermit without changing section names or review requirements.

Evidence

Compared the current template with the rollout baseline, reviewed repository guidance, and checked all four headings, the blank-template marker, and whitespace. All passed. No runtime tests run for this wording-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

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

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: this is a focused, useful template improvement that is not yet on Hermit’s main branch. No blocking correctness or security issues were found.

Priority: P3
Reviewed head: 321c05680f7c94585c76aba61cea28397ca18dc5

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused template improvement with preserved requirements and no identified 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 PR changes GitHub template prose only; the supplied template checks and inspected source support the change without a runtime-proof gate.
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 PR changes GitHub template prose only; the supplied template checks and inspected source support the change without a runtime-proof gate.
Evidence reviewed	6 items	Complete introduced change: The pinned delta changes only the PR template. All four section names remain, user impact moves before implementation rationale, and the maintainer-edit instruction remains available in the editor’s introductory comment. Whitespace validation passed. Current main still uses the older template: The main-branch template retains the previous wording and section order. A GitHub ref check confirmed main remains at this revision; the requested change is therefore not implemented there, and no fixed-release claim applies. Existing review guidance remains compatible: The PR-review Discord command requires the same four sections and maintainer editing permission. Its tests check section content rather than order; the template preserves those requirements.
Findings	None	None.
Security	None	None.

How this fits together

Hermit’s GitHub PR template guides contributors when writing descriptions for review. Its prompts shape how reviewers see the problem, impact, rationale, and validation.

flowchart LR
  A[Contributor opens PR] --> B[GitHub 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: This bot-authored PR changes GitHub template prose only; the supplied template checks and inspected source support the change without a runtime-proof gate.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Use one concise template that foregrounds outcomes and preserves visible risk, action, and validation summaries.

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

Not applicable: this changes contributor writing guidance rather than repairing a runtime failure.

Is this the best way to solve the issue?

Yes: editing the existing template is the narrowest approach, and its required sections remain compatible with current review guidance.

AGENTS.md: found, but no applicable review policy affected this item.

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

Labels

Label changes:

• add P3: This is low-risk contributor documentation polish with no runtime 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: This bot-authored PR changes GitHub template prose only; the supplied template checks and inspected source support the change without a runtime-proof gate.

Label justifications:

• P3: This is low-risk contributor documentation polish with no runtime 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: This bot-authored PR changes GitHub template prose only; the supplied template checks and inspected source support the change without a runtime-proof gate.

Evidence

What I checked:

• Complete introduced change: The pinned delta changes only the PR template. All four section names remain, user impact moves before implementation rationale, and the maintainer-edit instruction remains available in the editor’s introductory comment. Whitespace validation passed. (.github/pull_request_template.md:17, 321c05680f7c)
• Current main still uses the older template: The main-branch template retains the previous wording and section order. A GitHub ref check confirmed main remains at this revision; the requested change is therefore not implemented there, and no fixed-release claim applies. (.github/pull_request_template.md:27, 9b8cede7c0ad)
• Existing review guidance remains compatible: The PR-review Discord command requires the same four sections and maintainer editing permission. Its tests check section content rather than order; the template preserves those requirements. (src/commands/say.ts:22, 321c05680f7c)
• Merged template history and routing: GitHub identifies hannesrudolph as the author of the merged template-alignment PR chore: align pull request template #20. Local follow-history inspection failed on an unavailable object, so GitHub commit and PR metadata supplied the routing evidence instead. (.github/pull_request_template.md, ecbfda88ccb6)
• Linked rollout context: The body links docs: make PR descriptions plain-language first openclaw#146253, which GitHub confirms is merged and describes the same plain-language template direction. This supports the rollout rationale but does not establish implementation in Hermit.
• Proof scope: The complete supplied PR body reports template, heading, and whitespace checks. GitHub’s roboclaw-bot account profile identifies it as automation. This bot-authored wording change introduces no runtime behavior requiring contributor runtime proof. (.github/pull_request_template.md, 321c05680f7c)

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.