Skip to content

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

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 #161. 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

🦞👀
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

Codex review: needs maintainer review before merge.

What this changes

This PR clarifies how contributors should explain the affected people, current problem, and need independently of their proposed fix.

Example: A contributor fills out the problem section of a new PR.

  • Before: The guidance requests the affected workflow and symptom.
  • After: The guidance also asks whether readers can understand the problem without knowing the proposed fix.

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) Complete Markdown inspection and passing exact-head Worker CI support this focused documentation change.
Proof confidence 🐚 platinum hermit (4/6) Direct inspection covers this non-executable contributor guidance; 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: Reviewers may understand a proposed fix without understanding who needs it or why.
Reason: The maintainer-authored change makes the existing guidance more explicit without adding sections, gates, or runtime behavior.

Merge readiness

✅ Ready for maintainer review

Keep this maintainer-authored PR open: the documentation change is focused and useful, and review found no actionable defect.

Priority: P3
Reviewed head: dc7ee17123be7cbfc02112a7a803c8b256e51ec0

Before merge

None.

Findings

None.

Agent review details

How this fits together

GitHub loads the Markdown template into new PR descriptions, where comments guide contributors before reviewers assess their submissions.

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

Technical review

Best possible solution:

Retain the focused clarification in the existing template.

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 guidance change.

Is this the best way to solve the issue?

Editing the existing comment is a suitably small solution that preserves the established submission structure.

AGENTS.md: found and applied where relevant.

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

Provenance checked

Security

None.

Evidence

What I checked:

Likely related people:

  • Hannes Rudolph: Raw commit 5af4ab8 adds .github/pull_request_template.md:33 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 5af4ab8609ff; 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 21, 2026, 6:23 PM ET / 23:23 UTC.

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