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

Contributors are prompted to put the concrete outcome first and keep risks, migrations, required actions, and useful evidence visible. No product behavior, security boundary, compatibility, migration, or required operator action changes.

Why This Change Was Made

Carries over the approved wording from openclaw/openclaw#146253 while preserving the existing section names and maintainer-edit requirement. Hannes Rudolph (@hannesrudolph) is credited as co-author in the unchanged commit. This changes the GitHub PR description template, not an RFC proposal or its acceptance lifecycle.

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.
• CodeQL Analyze (actions) succeeded on unchanged head 6413529432f3d7e1f96439dce158d71e273bb039. Passing workflow checks are not authoring proof and do not establish merge readiness.

Observed GitHub authoring proof — September 15, 2026: used the exact HEAD template to author this existing PR via GitHub CLI 2.100.0, preserving every original template comment and heading. Live identity was verified as roboclaw-bot before the edit. GitHub saved the completed description; authoritative readback matched the submitted body byte-for-byte and retained the exact head/state. This is observed explicit-template authoring and save/readback proof, not browser-composer or automatic default-branch prefill proof. No runtime fix is claimed.

Observed-use transcript (temporary filenames normalized)

$ gh api user --jq .login
roboclaw-bot
$ gh api 'repos/openclaw/rfcs/contents/.github/pull_request_template.md?ref=6413529432f3d7e1f96439dce158d71e273bb039' -H 'Accept: application/vnd.github.raw+json'
[Exact HEAD template retrieved; filled in its four sections without deleting template instructions.]
$ gh pr edit 72 --repo openclaw/rfcs --body-file authored-body.md
https://github.com/openclaw/rfcs/pull/72
$ gh pr view 72 --repo openclaw/rfcs --json url,headRefOid,state,isDraft,body,updatedAt
headRefOid: 6413529432f3d7e1f96439dce158d71e273bb039
state: OPEN; isDraft: false
updatedAt: 2026-09-15T17:01:23Z
body equals submitted file: true
heading order:
## What Problem This Solves
## User Impact
## Why This Change Was Made
## Evidence
checkbox checklist: [] (none in exact template)
retained author-facing instruction:
**MUST:** Keep **Allow edits from maintainers** enabled for this PR so maintainers
can help update the branch when needed.
all original HTML instruction comments retained: true

The exact HEAD template has no checkbox checklist. Its original author-facing HTML comment, including the “Allow edits from maintainers” requirement, is retained verbatim rather than inventing checklist items.

[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 maintainer review before merge. Reviewed September 15, 2026, 1:06 PM ET / 17:06 UTC (Revision 2).

ClawSweeper review

What this changes

Updates the PR description template to put plain-language outcomes before technical rationale while keeping risks and evidence summaries visible.

Merge readiness

✅ Ready for maintainer review

This remains a useful, focused change absent from current main. The added authoring transcript resolves the previous proof concern, and no actionable patch defects were found.

Priority: P3
Reviewed head: 6413529432f3d7e1f96439dce158d71e273bb039

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, correct template revision with relevant observed authoring evidence and no remaining material review blockers.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): The supplied terminal transcript exercises the changed GitHub PR template through explicit CLI authoring and records successful save/readback with the intended headings and instructions preserved; that is sufficient for this wording change.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The supplied terminal transcript exercises the changed GitHub PR template through explicit CLI authoring and records successful save/readback with the intended headings and instructions preserved; that is sufficient for this wording change.
Evidence reviewed	6 items	Current main still uses the previous template: The verified default branch remains at the fetched SHA; its template places rationale before user impact and lacks the new concise-writing guidance. Complete introduced change inspected: The pinned base-to-head diff changes only template prose and section ordering. The maintainer-edit instruction remains author-visible in an HTML comment; no execution, permissions, dependencies, or persisted product settings change. Whitespace validation passed. After-change authoring evidence resolves prior concern: The fully supplied PR body records September 15 use of the exact head template through GitHub CLI 2.100.0, successful description save, and byte-for-byte readback retaining all four headings and instruction comments. This demonstrates explicit-template authoring; it does not claim browser composition or automatic default-branch prefill. The previous completed review had no findings and requested relevant after-change proof.
Findings	None	None.
Security	None	None.

How this fits together

This repository holds OpenClaw design proposals. Its GitHub PR template guides contributors in describing proposed changes and gives reviewers a consistent problem, impact, rationale, and evidence structure.

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

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Use the revised template to encourage concise descriptions while retaining visible material risks, required actions, and validation summaries.

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

Not applicable: this changes contributor guidance rather than fixing a runtime bug; the supplied transcript demonstrates use of the revised template.

Is this the best way to solve the issue?

Yes: editing the existing template is a narrow, maintainable way to improve description structure without adding competing guidance or changing the RFC lifecycle.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P3: This is a low-risk contributor-documentation improvement with no product runtime change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The supplied terminal transcript exercises the changed GitHub PR template through explicit CLI authoring and records successful save/readback with the intended headings and instructions preserved; that is sufficient for this wording change.
• proof: sufficient: Contributor real behavior proof is sufficient. The supplied terminal transcript exercises the changed GitHub PR template through explicit CLI authoring and records successful save/readback with the intended headings and instructions preserved; that is sufficient for this wording change.

Evidence

What I checked:

• Current main still uses the previous template: The verified default branch remains at the fetched SHA; its template places rationale before user impact and lacks the new concise-writing guidance. (.github/pull_request_template.md:27, 967d9aac7472)
• Complete introduced change inspected: The pinned base-to-head diff changes only template prose and section ordering. The maintainer-edit instruction remains author-visible in an HTML comment; no execution, permissions, dependencies, or persisted product settings change. Whitespace validation passed. (.github/pull_request_template.md:17, 6413529432f3)
• After-change authoring evidence resolves prior concern: The fully supplied PR body records September 15 use of the exact head template through GitHub CLI 2.100.0, successful description save, and byte-for-byte readback retaining all four headings and instruction comments. This demonstrates explicit-template authoring; it does not claim browser composition or automatic default-branch prefill. The previous completed review had no findings and requested relevant after-change proof. (.github/pull_request_template.md:21, 6413529432f3)
• Prior template ownership and related work: Pinned-main path history and the GitHub commit patch connect the existing template to hannesrudolph and merged chore: align pull request template #36. That earlier work established the previous template rather than implementing this revision. Local follow-history traversal encountered an unavailable object; GitHub path history and commit inspection supplied the routing evidence. (.github/pull_request_template.md, 4b76d31d30ec)
• Referenced wording change is merged in its source repository: GitHub confirms docs: make PR descriptions plain-language first openclaw#146253 merged on September 12. The reviewed body explicitly cites it as the wording source; this cross-repository merge does not establish implementation in openclaw/rfcs. (d23730ee7c54)
• Repository boundary and applicable guidance: README.md distinguishes RFC documents and their acceptance lifecycle from repository contribution infrastructure. No root or applicable nested AGENTS.md or maintainer-notes directory exists. The inspected dispatch workflow does not parse or depend on the changed section order. (README.md:83, 6413529432f3)

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.

History

Review history (1 earlier review cycle)

• reviewed 2026-09-12T19:49:44.293Z sha 6413529 :: needs real behavior proof before merge. :: none