docs: guide pull requests with problem-first descriptions

[hannesrudolph]

Related: #125

Additional instructions

MUST: Keep Allow edits from maintainers enabled for this PR so maintainers
can help update the branch when needed.

What Problem This Solves

Discrawl contributors and reviewing agents need PR descriptions that explain the concrete problem before the implementation. Without a consistent starting structure, descriptions can lead with code changes and leave reviewers to reconstruct why the change matters, who benefits, and what evidence supports it.

Why This Change Was Made

Add OpenClaw's current default pull-request template unchanged at GitHub's standard .github/pull_request_template.md location. It provides the four problem-first sections, optional linked-context guidance, user-facing title guidance, and the reminder to keep maintainer edits enabled.

The identical template was previously proposed in #125, which was closed without merging. Discrawl still has no default PR template; this proposal adds the current canonical template.

User Impact

Contributors opening new PRs through GitHub receive a problem-first description structure. Agents and command-line contributors can use the same repository template, and reviewers get consistent sections for the problem, rationale, impact, and evidence.

This is contributor-workflow guidance; there is no change to Discrawl's CLI, archive data, or runtime behavior.

Evidence

• Copied byte-for-byte from OpenClaw's template at commit 4ae4b5c.
• Both files have Git blob ID e902c4789b21765ea16dfb75e436db5801b6450b.
• git diff --check passed.
• The diff adds one Markdown file at GitHub's supported default-template path. Runtime tests are not applicable to this documentation-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 maintainer review before merge. Reviewed September 10, 2026, 4:11 PM ET / 20:11 UTC.

ClawSweeper review

What this changes

Adds a default GitHub pull-request template that guides contributors through the problem, rationale, user impact, and evidence.

Merge readiness

✅ Ready for maintainer review

This is a focused, useful documentation change with no blocking findings. The template is absent from current main, and the earlier proposal was closed without merging. Member-authored work also remains protected from automatic closure.

Priority: P3
Reviewed head: 8c22a0114dd3439b350e6e978b394117a78e2435

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused template addition with verified source identity, clean whitespace validation, and no blocking defects.
Proof confidence	🌊 off-meta tidepool	Not applicable: The member-authored PR adds only a static GitHub template; the ordinary contributor runtime-proof gate does not apply, and no authority-bearing behavior changes.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The member-authored PR adds only a static GitHub template; the ordinary contributor runtime-proof gate does not apply, and no authority-bearing behavior changes.
Evidence reviewed	5 items	Complete introduced change: The pinned base-to-head diff adds only the 65-line Markdown template; the complete patch was read and the whitespace check passed. Current-main and release necessity: The full current-main tree contains no default pull-request template, and the v0.14.1 .github tree also lacks it. No applicable AGENTS.md or maintainer-notes directory was found. Earlier proposal did not land: The supplied discussion identifies #125 as the identical earlier proposal; GitHub confirms it is closed with merged=false. It therefore does not supersede this landing candidate.
Findings	None	None.
Security	None	None.

How this fits together

Discrawl's contribution workflow receives proposed changes through GitHub pull requests. The template supplies description prompts that help contributors explain their work to reviewers.

flowchart LR
  A[Contributor opens pull request] --> B[Default repository template]
  B --> C[Problem and rationale]
  B --> D[User impact and evidence]
  C --> E[Reviewer assessment]
  D --> E

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Use one repository-default template to make contribution descriptions consistently explain the problem and supporting evidence.

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

Not applicable: this proposes contribution guidance rather than reporting a runtime defect.

Is this the best way to solve the issue?

Yes: a single default template is a narrow, maintainable way to provide the missing description structure, and the pinned source copy matches exactly.

AGENTS.md: not found in the target repository.

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

Labels

Label changes:

• add P3: This is low-risk contributor-workflow documentation with no runtime changes.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The member-authored PR adds only a static GitHub template; the ordinary contributor runtime-proof gate does not apply, and no authority-bearing behavior changes.

Label justifications:

• P3: This is low-risk contributor-workflow documentation with no runtime changes.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The member-authored PR adds only a static GitHub template; the ordinary contributor runtime-proof gate does not apply, and no authority-bearing behavior changes.

Evidence

What I checked:

• Complete introduced change: The pinned base-to-head diff adds only the 65-line Markdown template; the complete patch was read and the whitespace check passed. (.github/pull_request_template.md:1, 8c22a0114dd3)
• Current-main and release necessity: The full current-main tree contains no default pull-request template, and the v0.14.1 .github tree also lacks it. No applicable AGENTS.md or maintainer-notes directory was found. (5ef4faad55d0)
• Earlier proposal did not land: The supplied discussion identifies chore: align pull request template #125 as the identical earlier proposal; GitHub confirms it is closed with merged=false. It therefore does not supersede this landing candidate.
• Template source identity: GitHub identifies the claimed source template at the pinned commit with blob e902c4789b21765ea16dfb75e436db5801b6450b, matching the reviewed branch file. This is copied prose, with no dependency runtime or protocol contract. (.github/pull_request_template.md:1, 4ae4b5c2a464)
• Contributor-guidance history and inspection limits: README history identifies Peter Steinberger's documentation rewrite as adjacent routing context. Deeper README blame and pickaxe inspection failed because required historical blobs could not be retrieved; introduction attribution remains unverified. The broader GitHub template search was also unavailable, but the supplied related proposal and current tree were inspected. (README.md, 109e97872147)

Likely related people:

• Peter Steinberger: 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.