Skip to content

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

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

Rewords the PR template’s problem guidance to distinguish the affected person’s experience from the proposed fix.

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

  • Before: The guidance asks for the experienced problem and contrasts it with implementation terminology.
  • After: The guidance explicitly asks whether the problem makes sense without the proposed fix and contrasts a problem statement with a proposed action.

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) A focused documentation improvement supported by complete source inspection and successful checks, with no actionable findings.
Proof confidence 🐚 platinum hermit (4/6) The complete template and pinned diff were inspected; this documentation-only change requires no shipped CLI 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 action while still having to infer who needs it and why.
Reason: The maintainer-authored refinement makes the existing guidance more explicit while preserving its scope and structure.

Merge readiness

✅ Ready for maintainer review

This maintainer-authored PR makes a focused improvement to contributor guidance; no actionable defect or merge blocker was found.

Priority: P3
Reviewed head: 0eda1a0459bddf043fb3760f151e78bf86096a2c

Before merge

None.

Findings

None.

Agent review details

How this fits together

GitHub loads the Markdown template into new PR descriptions, where contributors read its hidden guidance and write the description reviewers receive.

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 wording change in the existing template.

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

No runtime bug is claimed; direct comparison establishes the existing and proposed contributor guidance.

Is this the best way to solve the issue?

Editing the existing guidance comment is the smallest complete approach and preserves the original reader-first purpose without adding a review gate.

AGENTS.md: found and applied where relevant.

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

Provenance checked

Security

None.

Evidence

What I checked:

  • Pinned change: The introduced diff changes only the problem-guidance HTML comment; visible headings and all other template content remain unchanged. (.github/pull_request_template.md:23, 0eda1a0459bd)
  • Original intent and ownership: docs: help contributors explain gogcli changes #1341 introduced reader-first guidance and credits hannesrudolph with directing it; the merged commit also records that coauthorship. (.github/pull_request_template.md:22, 351e62175513)
  • Repository policy: The complete root AGENTS.md was applied; no nested .github AGENTS.md, maintainer-notes directory, or pr-simplify skill was found. This contributor-template edit changes no released CLI behavior. (AGENTS.md:36, 0eda1a0459bd)
  • Current main and review state: The default branch remains at the pinned base with the earlier wording; this PR is MEMBER-authored and reported cleanly mergeable. (ae8dbb2eef93)
  • Validation: Whitespace checks passed, the checkout stayed clean, and the exact head has ten successful checks and two skipped checks with no failures; no target code was executed. (.github/pull_request_template.md, 0eda1a0459bd)
  • History boundary: The scoped history identifies the template-addition commit; following history reaches an unavailable object at that creation boundary, while the full addition, current-main blame, and original PR establish the relevant provenance. (.github/pull_request_template.md, 351e62175513)

Likely related people:

  • RoboClaw: Raw commit 351e621 adds .github/pull_request_template.md:22 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 351e62175513; 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 runtime 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 runtime 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:24 PM ET / 23:24 UTC.

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