Skip to content

docs: help PR authors explain the affected task and outcome - #161

Merged
hannesrudolph merged 1 commit into
mainfrom
docs/reader-first-pr-template
Nov 17, 2026
Merged

hannesrudolph merged 1 commit into
mainfrom
docs/reader-first-pr-template

Conversation

@hannesrudolph

Copy link
Copy Markdown
Member

What Problem This Solves

The current PR template does not clearly ask authors to lead with the affected task and outcome or summarize validation before commands.

User Impact

Contributors and reviewers get reader-first title, problem, and evidence prompts. There is no application-runtime change.

Why This Change Was Made

Applies the wording guidance from openclaw/openclaw#200319 with repository-specific examples. Preserves every existing heading and checklist item, existing privacy/security sections, and the optional Fixes prompt wherever present. No tests, review gates, permissions, or runtime settings are added.

Evidence

Read the current remote instructions and template. Checked balanced Markdown comments, whitespace, preservation of existing headings/checklist items, and retained contract wording. Publication uses one GitHub CLI mutation and changes only .github/pull_request_template.md; no clone, worktree, or local file is created. Runtime tests, dependency-backed validation, and independent review were not run by this API-only publication; existing required checks/reviews remain outstanding, not waived.

The prior Team candidate reported unmet local validation gates, missing dependencies/Go, and test failures. Those are retained limitations, not passing evidence. This draft does not claim the gates were resolved.

@clawsweeper

clawsweeper Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🦞👀
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 clawsweeper Bot added clawsweeper:intake:docs Preliminary submission classification; full source review pending. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed clawsweeper:intake:docs Preliminary submission classification; full source review pending. labels Nov 17, 2026
@clawsweeper

clawsweeper Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codex review: needs maintainer review before merge.

What this changes

This PR adds examples and prompts asking contributors to explain the affected task, outcome, and validation result in plain language.

Example: A contributor describes a remote desktop connection error change.

  • Before: The title might say “fix: update the relay error mapping.”
  • After: The template suggests “fix: explain why a remote desktop connection did not start.”

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) Direct Markdown inspection supports this focused documentation change; exact-head Worker CI passed, but all landing gates have not been independently established.
Proof confidence 🐚 platinum hermit (4/6) This changes non-executable contributor guidance at the existing template path, so application runtime proof is unnecessary.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Contributors can describe implementation details without making the affected task and validation result clear to reviewers.
Reason: The maintainer-authored direction adds concrete repository-specific examples without adding sections or gates; it follows the wording approach credited to openclaw/openclaw#200319.

Merge readiness

✅ Ready for maintainer review

Keep this maintainer-authored draft open; its documentation changes are coherent, and inspection found no actionable defect.

Priority: P3
Reviewed head: 3ea952d8e6aa6fb04b3d2f019ee797deb1341624

Before merge

None.

Findings

None.

Agent review details

How this fits together

GitHub loads the Markdown template into new PR descriptions, where its comments guide contributors before reviewers read the resulting submission.

flowchart LR
A[Template Markdown] --> B[GitHub PR editor]
B --> C[Contributor description]
C --> D[Maintainer review]
Loading

Technical review

Best possible solution:

Retain the repository-specific examples and validation guidance while preserving the existing template structure.

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

There is no runtime bug to reproduce; the original and revised Markdown directly establish the wording changes.

Is this the best way to solve the issue?

Editing the existing template is an appropriate solution, although some added prompts repeat guidance already present.

AGENTS.md: found and applied where relevant.

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

Provenance checked

  • PR template structure and plain-language guidance keeps the original intent (chore: align pull request template #79: Standardize submission structure so review and evidence collection are predictable.)
  • Problem statement length and reader-first wording keeps the original intent (docs: make PR descriptions plain-language first #131: Lead with the visible problem and resulting behavior before implementation details; this PR preserves that intent while allowing one to three sentences.)

Security

None.

Evidence

What I checked:

  • Verified patch, policy, history, and current GitHub state: The pinned introduced diff changes only the PR template, preserving its headings and existing requirements. Root AGENTS.md was read completely; no nested governing AGENTS.md, maintainer-notes directory, or pr-simplify skill was present. Current main remains at the supplied base SHA. Earlier template work in chore: align pull request template #79 established consistent submission structure, and docs: make PR descriptions plain-language first #131 established plain-language descriptions; this PR extends that direction. Both current discussion comments are review-status messages, with no substantive objection or approval. Exact-head Worker CI passed and its workflow runs pnpm check and pnpm test; Swift analysis remains in progress, and pnpm test:native completion is not established. No tests were run during this read-only review. Path history and blame identify the earlier contributors; git log --follow encountered an unavailable old object, while the relevant commits and original template blobs were independently readable. The checkout remained clean. (.github/pull_request_template.md:1, 3ea952d8e6aa)

Likely related people:

  • Hannes Rudolph: Raw commit 38cad49 adds .github/pull_request_template.md:3 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 38cad499e14e; files: .github/pull_request_template.md)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Labels

Label changes:

  • add P3: This is low-risk contributor documentation polish with no application behavior change.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

  • P3: This is low-risk contributor documentation polish with no application behavior 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.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed November 17, 2026, 11:37 AM ET / 16:37 UTC.

@hannesrudolph
hannesrudolph marked this pull request as ready for review November 17, 2026 17:35
@hannesrudolph
hannesrudolph merged commit 5af4ab8 into main Nov 17, 2026
12 checks passed
@hannesrudolph
hannesrudolph deleted the docs/reader-first-pr-template branch November 17, 2026 17:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant