Peter Steinberger
1abf60d28c
* fix(scripts): resolve pr tooling from a configurable root and preflight host git * fix(scripts): preserve PR tooling contracts in dependency checks and fixtures * test(scripts): match cross-checkout PR identity diagnostics * fix(scripts): preserve GitHub CLI host selection for PR reads * test(scripts): inject remote base drift at hosted verification
11 KiB
summary, read_when, title, sidebarTitle
| summary | read_when | title | sidebarTitle | |||
|---|---|---|---|---|---|---|
| How Barnacle and ClawSweeper feedback helps move OpenClaw pull requests through review. |
|
Pull request review flow | PR review flow |
This page explains the review flow after you open or update an OpenClaw pull request: what Barnacle and ClawSweeper do, how to improve the PR from their feedback, and what to check when automation stays quiet.
Barnacle and ClawSweeper help maintainers keep the review queue usable. They do not replace maintainer judgment.
Barnacle
Barnacle is deterministic GitHub triage. It looks for known queue-management cases and responds with labels, comments, or closures.
Barnacle may act when:
- a PR body is mostly empty or missing problem context;
- a PR has no useful evidence;
- a docs-only, test-only, refactor-only, CI-only, or infra change lacks linked maintainer context;
- a change looks like it belongs in ClawHub or a plugin instead of core;
- a branch carries unrelated work;
- an author has more than 20 open PRs.
Barnacle runs from trusted repository workflow code. It does not check out or run contributor code.
Most routing labels are maintainer or automation signals, so contributors do not need to add labels themselves.
ClawSweeper
ClawSweeper is the AI-assisted review and maintenance bot for OpenClaw repositories. It can review PRs, evaluate proof, leave durable review comments, and help maintainers with guarded repair or automerge flows.
A positive ClawSweeper result is supporting evidence, not maintainer approval. Maintainers still decide whether and when a PR is ready to merge.
ClawSweeper is queue-based. When you open a non-draft PR or mark a draft ready for review, it posts a short receipt comment right away, but the review itself still waits for a queue slot. Do not expect an immediate review after opening a PR, pushing a commit, or adding a review request. Label updates after a ClawSweeper run can also take time.
New PRs enter the ClawSweeper review queue. Maintainers can also queue review, repair, or automerge flows with labels or commands. For ordinary contributor updates, ask ClawSweeper for another review only after you have updated the branch, PR description, proof, or code. Then request a fresh review with a new PR comment:
@clawsweeper re-review
PR authors can also use @clawsweeper re-run; users with repository write
access can use either command on any open item. The plain
@clawsweeper review command is maintainer-only. Be patient: asking again
before the requested changes are present just adds queue noise.
When ClawSweeper leaves review conversations, treat them like normal review feedback and use the follow-up checklist below.
If a human contributor or maintainer has taken over the PR and is actively working on it, do not summon ClawSweeper or otherwise work on the PR at the same time. Let the human review or repair finish first. If activity stops, check whether the author was asked to provide proof or make other updates.
Improve a PR during review
Once Barnacle, ClawSweeper, or a maintainer responds, use that feedback as the next-step checklist for the PR.
- Read ClawSweeper's
Rank-up moves:andProof guidance:as the action list for that PR. Ratings and labels are review signals, not fixed merge targets. - Push the requested code or docs change, and update the PR description when the problem, solution, user impact, or evidence has changed.
- Add the requested proof, using evidence that matches the change.
- Resolve addressed review conversations yourself. Reply and leave a conversation open only when you need maintainer or reviewer judgment.
- Ask for a re-review only after the branch, PR description, evidence, and relevant CI results are current. Multiple update and review cycles between the author, maintainer, and ClawSweeper are normal.
- Keep discussion on the PR when possible. Move to
#clawtributorson Discord only when the PR needs maintainer coordination, automation appears blocked, or the next decision is hard to settle in GitHub comments. Include the PR link, current status, and the specific question or remaining evidence.
Keep the PR body current. Comments help with discussion, but the PR description is the durable summary maintainers and automation revisit.
status: ⏳ waiting on author means the next action is with the PR author:
update the branch, PR description, proof, or reply with the missing context
before asking for another review.
Useful evidence includes focused test output, CI results, screenshots, recordings, terminal output, live observations, redacted logs, or artifact links. For visual changes, include before and after screenshots when practical. For proof files, prefer linking CI artifacts, GitHub-uploaded screenshots or recordings, or a short redacted log excerpt. Do not commit generated proof files unless they are part of the actual docs, tests, or product change.
Redacting sensitive data is the contributor's responsibility. Remove secrets, tokens, private URLs, user data, and unrelated logs before posting proof.
OpenClaw also uses separate stale automation. Unassigned issues and PRs can be marked stale after 14 days of inactivity, then closed after 7 more idle days. Assigned PRs are marked stale 27 days after opening, regardless of later updates, then closed after 7 stale days without activity. If an assigned PR is still active, coordinate with the maintainer working on it.
Maintainer review artifacts
scripts/pr review-artifacts-init <PR> writes .local/review.json for the
current reviewed head. Its defaults are structurally valid and explicitly
unfinished: NEEDS WORK, performed: false, empty evidence arrays, and
tests.result: "not_run". Initialization preserves an existing artifact stamped
for the same PR and head, so it does not rewrite an older or partially filled
review.
Fill the JSON with review findings and evidence, then run
scripts/pr review-validate-artifacts <PR>. JSON owns the review; validation
prints its summary, and an existing .local/review.md is not authoritative.
Keep enum values bare, without annotations such as (allowed: ...):
| Field | Accepted values |
|---|---|
recommendation |
READY FOR /prepare-pr, NEEDS WORK, NEEDS DISCUSSION, NOT USEFUL (CLOSE) |
findings[].severity |
BLOCKER, IMPORTANT, NIT |
nitSweep.status (optional sweep) |
none, has_nits |
issueValidation.source |
linked_issue, pr_body, both |
issueValidation.status |
valid, unclear, invalid, already_fixed_on_main |
behavioralSweep.status |
pass, needs_work, not_applicable |
behavioralSweep.silentDropRisk |
none, present, unknown |
tests.result |
pass, fail, not_run |
docs |
up_to_date, missing, not_applicable |
changelog |
required, not_required |
nitSweep is optional and omitted from a fresh template. If supplied, it requires
performed: true, a status consistent with the NIT findings, and a non-empty
summary. Required issue and behavior summaries must also be non-empty, and each
finding needs a severity. Structural validity does not authorize preparation:
READY FOR /prepare-pr still requires completed issue and behavior review,
resolved substantive findings, and the applicable runtime proof.
When automation stays quiet
Automation may stay quiet when a maintainer is already handling the item, a review or repair request is still queued, the event is routine, or the ClawSweeper lane is not configured for the requested action.
It may also avoid action when a trusted workflow would need to run untrusted contributor code. In that case, maintainers use normal review or a safer workflow instead.
Troubleshooting
Maintainers can set OPENCLAW_PR_TOOLING_ROOT to a full checkout of this repository
to source materialized scripts/pr dependencies independently of a canonical checkout parked
on another branch. The environment setting takes precedence over
git config openclaw.pr.toolingRoot /path/to/tooling-checkout in the canonical
checkout; without either, dependency sourcing stays unchanged. Versions must
match the wrapper's trust-anchor manifest. On mismatch, a separate clean main
tooling checkout is fetched, fast-forwarded, and installed with
pnpm install --frozen-lockfile once, then rechecked. Dirty or non-main tooling
checkouts are refused with repair guidance; the canonical checkout is never
refreshed. The setting applies at both dependency materialization handoffs;
in-place wrappers keep their checkout's dependency context. Wrapper code selection
and trust stay unchanged.
Set OPENCLAW_PR_GIT to an absolute Git executable path if the host's default Git
is broken. The wrapper checks Git with a 10-second deadline and prints the selected
path and Xcode recovery hint on failure. API rate-limit failures identify the
resource used and show both GraphQL and REST core balances and reset times.
If ClawSweeper does not respond immediately, wait before retrying. The service is queue-based, and repeated comments or label changes can make the thread harder to review without making the queue faster.
Before asking for help, check:
- the PR description is current;
- the latest commit contains the requested change;
- CI has finished, or the PR body explains why any remaining failure is unrelated to the PR;
- the latest review request was made as a PR comment:
@clawsweeper re-review; - a maintainer or contributor is not already actively working on the PR;
- the latest request is not still within the normal ClawSweeper queue delay.
If there is still no ClawSweeper response several hours after the PR is current,
or if the PR appears blocked by automation, ask in #clawtributors on Discord.
Include the PR link, what you expected, when you asked, and what changed since
the last bot comment.
Forking the automation
Projects that want similar review automation can study or fork ClawSweeper: