docs: make PR descriptions plain-language first

[roboclaw-bot]

What Problem This Solves

Contributors need concise prompts that lead with the problem and concrete outcome.

User Impact

User impact: PR descriptions put user impact before technical rationale while keeping risks, required actions, and evidence visible. No product behavior changes.

Why This Change Was Made

Apply the plain-language direction from openclaw/openclaw#146253, preserving the established section names and maintainer-edit guidance. Contributor credit for @hannesrudolph is retained.

Evidence

• Isolated Codex autoreview: scoped-clean at P0–P2. Rebased onto current main without changing the template bytes.
• Live render proof: sent the before/after template source to GitHub's Markdown API, displayed that returned HTML alongside the exact source in a synthetic proof page, and inspected it in the real Chrome profile through the daemon-backed extension relay.
• Verified preview heading order: What Problem This Solves → User Impact → Why This Change Was Made → Evidence. Maintainer-edit guidance remains in the editor comment and does not appear in the rendered body.
• Both complete captures were inspected: synthetic repository template content only; no unrelated tabs, personal data, or credentials.
• git diff --check passes. Current-head CI is required before merge.

Before and after rendered proof

Before:

After:

[clawsweeper]

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

ClawSweeper review

What this changes

The PR shortens contribution prompts, places user impact before technical rationale, and keeps detailed output optional while requiring visible risks and evidence summaries.

Merge readiness

⛔ Blocked before merge - 2 items remain

This is a focused, useful template update that is not present on current main or v0.8.0. No actionable correctness or security defect was found; rendered-template proof remains outstanding.

Priority: P3
Reviewed head: 9dab7b37a982be50367fa25957c57bb169606fe1

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The patch is focused and sound, but the required rendered-template evidence is absent.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The changed GitHub template has wording and whitespace checks, but no supplied editor or preview observation showing the new prompts and rendered section order; the changed file is outside the docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The changed GitHub template has wording and whitespace checks, but no supplied editor or preview observation showing the new prompts and rendered section order; the changed file is outside the docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Repository policy: Read the complete root AGENTS.md; its contribution and evidence guidance applies. No nested AGENTS.md or matching maintainer notes were found under the inspected directories. Verified introduced change: The complete pinned base-to-head diff changes only the PR template. All four section names remain, user impact moves earlier, and the maintainer-edit instruction remains in the editor-facing HTML comment. Current main comparison: Current main retains the longer prompts and places rationale before user impact, so this exact update remains useful.
Findings	None	None.
Security	None	None.

How this fits together

GitHub uses this repository’s pull request template to seed contributor descriptions. Its prompts guide how contributors explain changes and provide evidence for reviewers.

flowchart LR
  A[Contributor opens PR] --> B[Repository template]
  B --> C[Problem and user impact]
  C --> D[Rationale and evidence]
  D --> E[Reviewer assessment]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The changed GitHub template has wording and whitespace checks, but no supplied editor or preview observation showing the new prompts and rendered section order; the changed file is outside the docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Complete next step (P2) - Add editor/preview evidence for the updated template, preferably screenshots or a short recording, with private information redacted. Updating the PR body should trigger a fresh review; otherwise ask a maintainer to comment @clawsweeper re-review.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep one concise contribution template that foregrounds outcomes while leaving material risks, required actions, and evidence visible.

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

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

Is this the best way to solve the issue?

Yes: editing the existing template is the narrowest solution, preserves the established section names, and follows the linked merged template precedent.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This is contribution-documentation polish with no product runtime change.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed GitHub template has wording and whitespace checks, but no supplied editor or preview observation showing the new prompts and rendered section order; the changed file is outside the docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P3: This is contribution-documentation polish with no product runtime change.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed GitHub template has wording and whitespace checks, but no supplied editor or preview observation showing the new prompts and rendered section order; the changed file is outside the docs/ exemption. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Repository policy: Read the complete root AGENTS.md; its contribution and evidence guidance applies. No nested AGENTS.md or matching maintainer notes were found under the inspected directories. (AGENTS.md:42, 9dab7b37a982)
• Verified introduced change: The complete pinned base-to-head diff changes only the PR template. All four section names remain, user impact moves earlier, and the maintainer-edit instruction remains in the editor-facing HTML comment. (.github/pull_request_template.md:17, 9dab7b37a982)
• Current main comparison: Current main retains the longer prompts and places rationale before user impact, so this exact update remains useful. (.github/pull_request_template.md:40, c1f351687f97)
• Latest release comparison: The v0.8.0 template also contains the previous wording and section order. (.github/pull_request_template.md:40, e78e71836812)
• Template history and routing: GitHub identifies hannesrudolph as the author of the merged template-alignment PR chore: align pull request template #157. Local follow-history inspection stopped on an unavailable promisor object; the GitHub commit and PR endpoints supplied the relevant history instead. (.github/pull_request_template.md, 041bf4bfd670)
• Linked template precedent: The PR explicitly adopts the template direction from docs: make PR descriptions plain-language first openclaw#146253, which GitHub confirms is merged. That supports the wording direction but does not establish implementation in clawpatch.

Likely related people:

• hannesrudolph: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add a redacted screenshot or recording of the updated template in GitHub’s PR editor and preview, showing the prompts and section order.

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.