clawhub-pr-maintainer

在审查、分类、验证或讨论 ClawHub GitHub 问题或拉取请求时使用，包括作者上下文、CI、UI 证明、证据、标签、关闭决策和维护者移交。

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

## Decide UI Proof Mode

Use the `clawhub-ui-proof` skill when the maintainer/agent should generate new
visual evidence.

- `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.

## Final Review Comment With Proof

If this review generated `proof:ui` artifacts, publish them before the final PR
review comment. Do not leave only local `.artifacts/...` paths in a PR comment;
they are useful to the maintainer locally but invisible to GitHub readers.

Use:

```sh
bun run proof:publish -- --proof-dir .artifacts/clawhub-ui-proof/<timestamp> --target-pr <number>
```

`proof:publish` copies the selected files to the `qa-artifacts` branch and
upserts a marker-backed PR comment with a **ClawHub UI Proof** section.

That comment includes:

- the proof mode (`before-after` or `feature`)
- the `report.md` result summary
- the most relevant per-step screenshots
- inline video previews when GIF previews are present
- links to full-run MP4s
- links to raw proof files on the artifact branch

Use `--dry-run` before publishing if you need to inspect the generated comment.
If publishing fails because credentials are missing, report the local proof
directory and the failed command instead of posting a comment that claims
evidence is 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.
- Keep maintainer comments short: finding, evidence, requested action, and
  verification path.
- When no proof artifacts were generated, `gh pr comment --body-file` is fine.
  When proof artifacts were generated, use `proof:publish` so screenshots/videos
  are published before posting.
- Do not close more than five issues/PRs in one action without explicit
  confirmation and the exact target list.

---

## 中文说明

# ClawHub PR 维护者

将此技能用于面向维护者的 ClawHub GitHub 工作流，而非普通的实现工作。

## 从实时 GitHub 状态开始

- 针对 `openclaw/clawhub` 使用 `gh pr view` 或 `gh issue view`；在评论、打标签、关闭或推荐合并之前，先核实实时状态。
- 对于 PR，阅读标题、正文、作者、标签、评论、文件、提交、状态检查、审查状态和关联的 issue。
- 简要呈现作者身份：在有用时给出 GitHub 名称/登录名和账户年龄。将身份视为分类信号，绝不要将其本身作为证据。

常用的只读命令：

```sh
gh pr view <number> --repo openclaw/clawhub --json title,body,author,labels,comments,files,commits,statusCheckRollup,reviewDecision,url
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}'
```

## 审查证据标准

- 对于 bug 修复，要求症状证据、在所触代码路径中的合理根因，以及回归测试或聚焦的手动验证之一。
- 对于 UI 变更，当行为在视觉上有实质意义时，要求截图或视频。将测试作为补充证据，而非可见验证的替代品。
- 当变更的行为尚未被实际执行时，不要仅凭 PR 文字、AI 论证或 CI 通过就合并或推荐合并。
- 对于贡献者提供的截图/视频/日志，直接检查该工件并说明它证明了什么。不要仅仅为了检查现有证据而重新运行 `proof:ui`。

## 决定 UI 验证模式

当维护者/代理应当生成新的视觉证据时，使用 `clawhub-ui-proof` 技能。

- `before-after`：bug 修复、回归、文案变更、布局变更，或任何主分支对比候选分支能厘清变更的 PR。
- `feature`：新页面、新流程、新 UI 状态，或在 `origin/main` 上无法存在的行为。
- 不生成证据：仅文档、仅后端、仅测试、仅元数据，或贡献者证据已足够的情况。

在 `.artifacts/proof-scenarios/` 下编写一个临时的 Playwright 场景；不要推断手动点击。在发布之前将截图和视频保留在 `.artifacts/` 中。切勿提交证据工件。

## 带证据的最终审查评论

如果本次审查生成了 `proof:ui` 工件，请在最终 PR 审查评论之前发布它们。不要在 PR 评论中只留下本地的 `.artifacts/...` 路径；这些路径对维护者本地有用，但对 GitHub 读者不可见。

使用：

```sh
bun run proof:publish -- --proof-dir .artifacts/clawhub-ui-proof/<timestamp> --target-pr <number>
```

`proof:publish` 将所选文件复制到 `qa-artifacts` 分支，并更新插入一条带标记的、含有 **ClawHub UI Proof** 章节的 PR 评论。

该评论包括：

- 验证模式（`before-after` 或 `feature`）
- `report.md` 结果摘要
- 最相关的逐步截图
- 当存在 GIF 预览时的内联视频预览
- 完整运行 MP4 的链接
- 工件分支上原始证据文件的链接

如果你需要检查生成的评论，请在发布前使用 `--dry-run`。如果因缺少凭据导致发布失败，请报告本地证据目录和失败的命令，而不是发布一条声称已附上证据的评论。

## ClawSweeper

ClawSweeper 是一旦配置好 ClawHub 派发后用于自动化 PR/issue 审查的机器人控制平面。在此之前，使用此技能进行手动维护者审查。如果 ClawSweeper 已发布审查，将其作为证据阅读，但在采取行动前先核实实时 PR 状态。

## 评论与标签

- 使用字面的多行评论正文或 `--body-file`；切勿传递转义的 `\n` 字符串。
- 保持维护者评论简短：发现、证据、请求的操作和验证路径。
- 当未生成证据工件时，使用 `gh pr comment --body-file` 即可。当生成了证据工件时，使用 `proof:publish`，以便在发布前先发布截图/视频。
- 未经明确确认和确切的目标列表，不要在一次操作中关闭超过五个 issue/PR。