diff --git a/.agents/skills/openclaw-pr-maintainer/SKILL.md b/.agents/skills/openclaw-pr-maintainer/SKILL.md index d703af32673c..d2af845049d5 100644 --- a/.agents/skills/openclaw-pr-maintainer/SKILL.md +++ b/.agents/skills/openclaw-pr-maintainer/SKILL.md @@ -193,6 +193,29 @@ gh pr view --json additions,deletions,changedFiles \ - Judge solution quality, not only correctness. Ask whether the PR is the clean owner-boundary fix or a wart/workaround that should be replaced by a small refactor, moved seam, contract change, or deletion of duplicate logic. - Mention the main files read when the verdict depends on code-path evidence. +## 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 issue/PR/proof. +2. Trace current behavior from entry point to failure or decision point. +3. Read touched files, callers, callees, owner modules, adjacent tests, and relevant docs. +4. Read sibling surfaces that should share the invariant or could be broken by a one-sided fix. +5. Compare against current `origin/main` and shipped behavior when regression/compat matters. +6. Inspect upstream dependency/Codex source or docs for dependency-backed behavior. +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. + +If the best-fix answer is only "maybe", keep reading or state the missing evidence. Do not call proof sufficient until the best-fix judgment is explicit. + ## Enforce the bug-fix evidence bar - Never merge a bug-fix PR based only on issue text, PR text, or AI rationale. diff --git a/AGENTS.md b/AGENTS.md index 30d48ae7c8c2..9f79067dcf60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,7 @@ Skills own workflows; root owns hard policy and routing. - Plugin APIs, provider routing, auth/session state, persisted preferences, config loading, config/default additions, migrations, setup, startup checks, and fallback behavior are compatibility/upgrade-sensitive. Treat config breaks, new config/default surfaces, removed fallbacks, fail-closed changes, stricter validation, or new operator action as merge risk even with green CI when they can affect existing users, upgrades, provider/plugin behavior, or maintainer operations. - For PRs that add, remove, or change config/default surfaces with possible compatibility, upgrade, provider/plugin, operator, setup, startup, or fallback impact, ClawSweeper review should emit a `reviewMetrics` entry when practical. The metric should name the count and direction of the changes, such as added, changed, or removed config/default surfaces, and explain why the metric matters before merge. When the metric indicates concrete merge risk, also surface the concern in `risks`, use `mergeRiskLabels` when the risk matches the label rubric, make `bestSolution` name the desired pre-merge state, and ensure `labelJustifications` explain the specific reason rather than restating the label. - Review whole decision surfaces, not only the touched runtime, provider, channel, harness, plugin seam, or context path. Check sibling Codex/Pi-style runtimes, provider/model routing, channel delivery, gateway/protocol, plugin SDK, and context-management paths when relevant. +- Every PR review must explicitly ask whether the PR is the best fix, not merely a plausible fix. Verdicts need a best-fix judgment backed by enough code reading to compare owner boundaries, callers, siblings, tests, docs, current `main`, shipped behavior when relevant, and dependency/Codex contracts when involved. - One-sided fixes need sibling-surface proof, an explanation for why siblings are unaffected, or explicit follow-up work. - Changelog findings: see Docs / Changelog. - Public ClawSweeper comments prefer `https://docs.openclaw.ai/...` when a public docs page exists; structured evidence still cites repo files, lines, SHAs.