clawhub-pr-maintainer

---
name: clawhub-pr-maintainer
description: Use when reviewing, triaging, validating, or discussing ClawHub GitHub issues or pull requests, including author context, CI, UI proof, evidence, labels, close decisions, and maintainer handoff.
---

# ClawHub PR Maintainer

Use this skill for maintainer-facing ClawHub GitHub workflow, not for ordinary
implementation work.

## Start With Live GitHub State

- Use `gh pr view` or `gh issue view` against `openclaw/clawhub`; verify live
  state before commenting, labeling, closing, or recommending merge.
- For PRs, read title, body, author, labels, comments, files, commits, status
  checks, review state, and linked issues.
- Surface author identity briefly: GitHub name/login and account age when
  useful. Treat identity as triage signal, never as proof by itself.

Common read-only commands:

```sh
gh pr view <number> --repo openclaw/clawhub --json title,body,author,labels,comments,files,commits,statusCheckRollup,reviewDecision,url,additions,deletions,changedFiles
gh issue view <number> --repo openclaw/clawhub --json title,body,author,labels,comments,state,url
gh api users/<login> --jq '{login,name,created_at,type}'
```

## Review Evidence Bar

- For bug fixes, require symptom evidence, a plausible root cause in the touched
  code path, and either a regression test or focused manual proof.
- For UI changes, require screenshots or video when the behavior is meaningfully
  visual. Use tests as supplemental evidence, not a substitute for visible proof.
- Do not merge or recommend merge based only on PR prose, AI rationale, or green
  CI when the changed behavior has not been exercised.
- For contributor-provided screenshots/videos/logs, inspect the artifact
  directly and state what it proves. Do not rerun `proof:ui` just to inspect
  existing evidence.

## Structure PR Review Output

- Start every PR review with 1-3 plain sentences explaining what the change does
  and why it matters.
- Show size near the top as `LOC: +x/-y (N files)`, using live PR stats or
  local diff stats.
- Then list findings first. If none, say `No blocking findings` or
  `No findings`.
- Always answer: affected ClawHub surface, bug or behavior being changed,
  evidence checked, and best-fix verdict.
- For bug/regression fixes, include a compact `Provenance:` line when a bounded
  history pass identifies it. Separate code author, PR author,
  merger/committer, current PR author, PR number, and date when those differ.
  If the blamed PR was merged by automation, identify the human trigger when
  practical; otherwise say trigger unknown.

## Read Beyond The Diff

- For code-path bug, regression, or behavior changes, review the surrounding
  path, not just changed lines. Open the runtime entry point, owner module, one
  caller, one callee, adjacent tests, and sibling surfaces that should share the
  invariant.
- For docs/config/process-only changes, read the changed file, its linked or
  adjacent source of truth, and any route/workflow/template the change claims to
  affect. Do not require runtime caller/callee evidence when no runtime path
  exists.
- Compare against current `origin/main` behavior or current published docs when
  regression, compatibility, or user-visible docs accuracy matters.
- For dependency-backed behavior, read the upstream docs/source/types before
  judging API use, defaults, output shapes, errors, timeouts, memory behavior, or
  compatibility.
- Mention the main files or contracts read when the verdict depends on
  code-path, docs, config, or workflow evidence.
- If a required path is uninspected, keep reading or mark
  `Remaining uncertainty`; do not call the PR best, proof-sufficient, or
  merge-ready.

## Best-Fix Review Loop

Every PR review must explicitly answer: "Is this the best fix, or only a
plausible fix?"

Before verdict:

1. Reconstruct the bug, feature need, or behavior claim from the issue, PR, and
   proof.
2. For code-path changes, trace current behavior from entry point to failure or
   decision point.
3. For docs/config/process-only changes, trace the reader/operator workflow or
   automation path the change is meant to clarify.
4. Read touched files, relevant callers/callees for code changes, adjacent docs
   or tests, owner modules, and relevant source-of-truth docs.
5. Read sibling surfaces that should share the invariant or could be broken by a
   one-sided fix.
6. Compare against current `origin/main` and shipped behavior when relevant.
7. Identify at least one alternative fix location or shape, then reject it with
   evidence.

Review output must include:

- `Best-fix verdict:` best / acceptable mitigation / wrong layer / too narrow /
  too broad.
- `Alternatives considered:` 1-3 concrete alternatives and why rejected.
- `Code read:` compact list of main files/contracts checked.
- `Remaining uncertainty:` what was not proven.

## Enforce Bug-Fix Evidence

- Never merge a bug-fix PR based only on issue text, PR text, or AI rationale.
- Before recommending merge for a bug fix, require:
  1. symptom evidence such as a repro, logs, failing test, or focused manual
     proof
  2. a verified root cause in code with file/line
  3. blame-backed provenance for regressions when traceable, or commit SHA/date
     when no PR is traceable
  4. a fix that touches the implicated code path
  5. a regression test when feasible, or explicit manual verification plus a
     reason no test was added
- If the claim is unsubstantiated or likely wrong, request evidence or changes
  instead of recommending merge.

## Decide UI Proof Mode

Generate new visual evidence with the best proof runtime available in the
current session. Use Crabbox through `bun run proof:ui` only when a Crabbox
skill or working Crabbox capability is available. Otherwise ignore Crabbox and
run the existing Playwright proof runtime against a real local ClawHub instance;
missing Crabbox access is not a blocker.

- `before-after`: bug fixes, regressions, changed copy, changed layout, or any
  PR where main-vs-candidate comparison clarifies the change.
- `feature`: new page, new flow, new UI state, or behavior that cannot exist on
  `origin/main`.
- No generated proof: docs-only, backend-only, tests-only, metadata-only, or
  already-sufficient contributor evidence.

Write a temporary Playwright scenario under `.artifacts/proof-scenarios/`; do
not infer manual clicks. Keep screenshots and videos in `.artifacts/` until
publishing. Never commit proof artifacts.

For the local fallback, start ClawHub with the relevant local Convex state and
run the scenario through the local Playwright runner:

```sh
bun run proof:ui -- --runner local --mode feature \
  --scenario .artifacts/proof-scenarios/<name>.pw.ts \
  --candidate-url <local-clawhub-url>
```

For before/after proof, run the same scenario against an `origin/main` checkout
and the candidate checkout, then pass both URLs with `--baseline-url` and
`--candidate-url`. The runner accepts only localhost or loopback URLs and writes
publishable `baseline/` and `candidate/` artifacts. Use the Codex app browser to
inspect the running local instances and captured evidence.

## Final Review Comment With Proof

Use [proof-video](../proof-video/SKILL.md) for capture, editing, inspection and
publication. Capture from the real running ClawHub instance and inspect every
final image/video before uploading it. Lead with the successful candidate;
label any failed baseline separately and state companion fixes and simulations.

Attach inspected media directly to the PR with native GitHub attachments:

```sh
gh pr comment <number> --repo openclaw/clawhub \
  --body-file .artifacts/proof/comment.md \
  --attach .artifacts/proof/after.mp4 \
  --attach '.artifacts/proof/before.png#Before' \
  --attach '.artifacts/proof/after.png#After'
```

Videos use bare uploaded URLs so GitHub renders players; do not add video alt
text. Include exact refs, the tested flow, validation and limitations in the
comment itself. Verify the final comment and return its direct link.

Never push proof assets or generated reports to any product repository branch,
including `qa-artifacts`. The old `proof:publish` helper is retired. Do not leave
only local paths or links to a source-tree directory as published evidence.
If attachment upload fails, retain the local files and report the precise
blocker instead of claiming they are attached.

## ClawSweeper

ClawSweeper is the bot control plane for automated PR/issue review once ClawHub
dispatch is configured. Until then, use this skill for manual maintainer review.
If ClawSweeper has posted a review, read it as evidence but verify live PR state
before acting.

## Commenting And Labels

- Use literal multiline comment bodies or `--body-file`; never pass escaped
  `\n` strings.
- For issue comments and PR comments containing backticks or shell characters,
  prefer a single-quoted heredoc or `--body-file` over inline `-b` bodies.
- Do not wrap issue or PR refs like `#123` in backticks when you want GitHub to
  auto-link them.
- Keep maintainer comments short: finding, evidence, requested action, and
  verification path.
- Use `gh pr comment --body-file`; add `--attach` for inspected media. Follow
  the proof-video skill for safe updates to an existing proof comment.
- Do not close more than five issues/PRs in one action without explicit
  confirmation and the exact target list.

More agent context in clawdbot/clawdhub

64 other files this repository gives its agents, the first 60 shown.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• openclaw/clawhub9.5k