docs: make PR descriptions plain-language first

[roboclaw-bot]

Related: openclaw/openclaw#146253

What Problem This Solves

The template encouraged long descriptions before stating the user-visible outcome.

User Impact

Contributors receive shorter, plain-language prompts that keep risks, required actions and evidence visible. No runtime changes.

Why This Change Was Made

Apply the approved core template while retaining all four section names and the instruction to allow maintainer edits. Preserve Hannes Rudolph's contributor credit.

Evidence

• Reviewed the complete template diff and preserved section names, blank-template comment marker and maintainer-edit instruction.
• Isolated Codex autoreview at P0–P2: scoped-clean.
• Built the CLI from head 355d87da2ae1d7df4e5b61062e95736ac2e60044; --version returned 0.15.1-0.20260912193507-355d87da2ae1, and metadata --json contained schema_version.
• Exact-head CI: https://github.com/openclaw/discrawl/actions/runs/34714601388.

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

ClawSweeper review

What this changes

The PR shortens contributor prompts, places user impact before implementation rationale, and keeps risks and evidence summaries visible.

Merge readiness

⛔ Blocked before merge - 1 item remains

This remains a useful, focused template improvement that is absent from main and the latest release. No actionable correctness or security defect was found.

Priority: P3
Reviewed head: 355d87da2ae1d7df4e5b61062e95736ac2e60044

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Recorded reviewer rating: A focused wording improvement with preserved section names, a clean whitespace check, and no concrete 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 automation-authored PR changes only contributor prompts; the bot-author exemption applies, and the reported static checks match the changed surface.
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 automation-authored PR changes only contributor prompts; the bot-author exemption applies, and the reported static checks match the changed surface.
Evidence reviewed	6 items	Verified introduced change: The complete pinned diff changes only the Markdown template, preserves all four heading names, retains the maintainer-edit instruction inside an author-facing comment, and adds explicit guidance to keep risks visible. Main and release still contain the earlier template: Main retains the longer prompts and places rationale before impact. Inspection of v0.15.0 also showed the earlier wording; the read-only whitespace check passed. Merged template history and routing: GitHub verifies that #213 merged the existing template. Its commit records hannesrudolph as author and adds the template; local raw commit inspection confirms the recorded parent. A deeper follow-history traversal encountered an unavailable object, but GitHub supplied the relevant addition patch.
Findings	None	None.
Security	None	None.

How this fits together

Discrawl’s GitHub pull request template guides contributors when writing descriptions. It organizes the problem, impact, rationale, and evidence that reviewers use to assess contributions.

flowchart LR
  A[Contributor opens a PR] --> B[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: This automation-authored PR changes only contributor prompts; the bot-author exemption applies, and the reported static checks match the changed surface.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep one concise repository template that leads with the problem and outcome while preserving visible risks, required actions, and validation evidence.

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

Not applicable: this changes contribution guidance rather than repairing a runtime failure; the complete template and pinned diff were inspected.

Is this the best way to solve the issue?

Yes: editing the existing template is a narrow, maintainable way to improve descriptions without adding competing guidance or changing the required section names.

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

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

Labels

Label changes:

• add P3: This is low-risk contributor-documentation polish with no application 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 automation-authored PR changes only contributor prompts; the bot-author exemption applies, and the reported static checks match the changed surface.

Label justifications:

• P3: This is low-risk contributor-documentation polish with no application 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 automation-authored PR changes only contributor prompts; the bot-author exemption applies, and the reported static checks match the changed surface.

Evidence

What I checked:

• Verified introduced change: The complete pinned diff changes only the Markdown template, preserves all four heading names, retains the maintainer-edit instruction inside an author-facing comment, and adds explicit guidance to keep risks visible. (.github/pull_request_template.md:17, 355d87da2ae1)
• Main and release still contain the earlier template: Main retains the longer prompts and places rationale before impact. Inspection of v0.15.0 also showed the earlier wording; the read-only whitespace check passed. (.github/pull_request_template.md, 2eb4aae89549)
• Merged template history and routing: GitHub verifies that docs: guide pull requests with problem-first descriptions #213 merged the existing template. Its commit records hannesrudolph as author and adds the template; local raw commit inspection confirms the recorded parent. A deeper follow-history traversal encountered an unavailable object, but GitHub supplied the relevant addition patch. (.github/pull_request_template.md:24, c55ff3dad74b)
• Linked rollout context: The explicitly linked docs: make PR descriptions plain-language first openclaw#146253 is merged and describes the same plain-language template direction, including checks of blank and filled descriptions. This supports the rollout context but does not establish implementation in Discrawl. (d23730ee7c54)
• Proof scope and author context: The complete captured PR body reports wording, headings, blank-template marker, and whitespace checks, with no runtime claim. The RoboClaw profile identifies the account as automation, supporting the bot-author proof exemption despite GitHub classifying the account type as User. (355d87da2ae1)
• Applicable policy inspection: No root or .github ancestor AGENTS.md exists, and no maintainer-notes directory exists. The AGENTS.md under the autoreview skill is outside the changed path’s scope. (355d87da2ae1)

Likely related people:

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