Skip to content

docs: help PR reviewers understand the problem before the fix - #335

Merged
hannesrudolph merged 1 commit into
mainfrom
docs/pr-template-problem-before-fix-202682
Nov 21, 2026
Merged

hannesrudolph merged 1 commit into
mainfrom
docs/pr-template-problem-before-fix-202682

Conversation

@hannesrudolph

Copy link
Copy Markdown
Member

What Problem This Solves

A PR can describe the fix in plain language without telling reviewers who is affected, what happens today, or why it matters. That leaves reviewers guessing at the problem before they can judge the fix.

User Impact

The template asks authors to describe the problem independently of the fix and shows the difference with a good and bad example. There is no runtime change.

Why This Change Was Made

This brings the problem-statement guidance from openclaw/openclaw#202682 into the template updated in #332. The rest of the template stays as it is.

Evidence

Verified that only the problem-guidance comment changes and that all text outside HTML comments is unchanged. No runtime tests were run for this template-only change.

@clawsweeper

clawsweeper Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
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 21, 2026
@clawsweeper

clawsweeper Bot commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge.

What this changes

Expands the PR template’s problem-statement guidance with affected-user prompts and contrasting problem-versus-fix examples.

Example: A contributor describes a change to background checks.

  • Before: The template requests one short problem sentence without contrasting it with a proposed fix.
  • After: The template contrasts model allowance consumed before monitoring is requested with the fix-only statement “Turn off periodic checks on fresh installs.”

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) A useful, narrowly scoped editorial change supported by complete diff inspection and passing applicable validation.
Proof confidence 🐚 platinum hermit (4/6) This documentation-only change is directly inspectable in the template and requires no shipped-runtime demonstration.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Reviewers can understand a proposed fix while still having to infer who is affected and why the underlying problem matters.
Reason: The maintainer-authored direction supplies a concrete distinction at the point contributors write their problem statement, at minimal maintenance cost.

Merge readiness

✅ Ready for maintainer review

Keep this PR open: it is a useful maintainer-authored documentation change absent from main, with no actionable defects found.

Priority: P3
Reviewed head: 0225647b7b02c0cf1af4b7d4b391a54f7350e49c

Before merge

None.

Findings

None.

Agent review details

How this fits together

GitHub seeds new PR descriptions from this Markdown template; contributors read its comments and supply the problem, impact, approach, and evidence for reviewers.

flowchart LR
  A[Contributor opens PR] --> B[GitHub loads template]
  B --> C[Contributor reads guidance]
  C --> D[Contributor writes description]
  D --> E[Reviewer assesses problem and fix]
Loading

Technical review

Best possible solution:

Land the focused guidance in the existing template while preserving its visible structure and illustrative-example caveat.

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

There is no runtime bug to reproduce; the complete base and head templates directly establish the editorial difference.

Is this the best way to solve the issue?

The existing template is the appropriate owner, and the focused edit clarifies the problem statement without introducing machinery or review gates.

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

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

Provenance checked

  • Problem-statement guidance keeps the original intent (0cb974f: Lead with concise plain-language problems and outcomes while keeping material risks and maintainer instructions visible.)

Security

None.

Evidence

What I checked:

Likely related people:

  • Hannes Rudolph: Raw commit e5633b0 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: e5633b0f8ef4; files: .github/pull_request_template.md)
  • roboclaw-bot: Raw commit 38d16cf adds .github/pull_request_template.md:17 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 38d16cff5204; 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: Contributor documentation polish with no runtime, automation, or persisted-state 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: Contributor documentation polish with no runtime, automation, or persisted-state 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 21, 2026, 6:22 PM ET / 23:22 UTC.

@hannesrudolph
hannesrudolph merged commit c1d40fd into main Nov 21, 2026
20 checks passed
@hannesrudolph
hannesrudolph deleted the docs/pr-template-problem-before-fix-202682 branch November 21, 2026 23:23
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