autoreview

Auto Review

这是流程类 Skill，默认仅在用户显式调用 $autoreview 时运行。

Run the bundled structured review helper as a closeout check. This is code review, not Guardian auto_review approval routing.

Codex review is the built-in default when no engine is set; AUTOREVIEW_ENGINE changes that default (see Environment defaults). The built-in Codex default uses gpt-5.6-sol with high reasoning, then retries once with gpt-5.6-terra only when the account cannot access Sol. Claude review is optional and inherits the current Claude Code model and effort unless --model or --thinking is set. BB session review launches a fresh BB thread with the invoking thread's provider, model, reasoning, and service-tier configuration; it is an explicit, non-host-read-isolated mode.

For user-visible behavior, pair autoreview with behavior-validator. Autoreview is source-aware and judges the change bundle; behavior validation is source-blind and judges the running product or tool against a behavior contract. A clean autoreview is not proof that a UI, CLI, API, or generated artifact works from the user's perspective.

Use when:

• user asks for Codex review / Claude review / Pi review / autoreview / second-model review
• user asks for a BB session/thread review of trusted input from an active BB thread
• after non-trivial code edits, before final/commit/ship
• reviewing a local branch or PR branch after fixes
• no reviewer CLI is installed: the subagent engine reviews through the host agent, but it is a non-independent self-review (see Subagent Engine)

Do not require autoreview for a change whose entire diff is prose-only internal notes or SKILL.md documentation. Still inspect the diff directly and run the repository's lightweight documentation validation, if any. This exception does not cover user-facing documentation, executable examples, configuration, scripts, generated files, or behavior changes.

Contract

• Honor --max-priority and AUTOREVIEW_MAX_PRIORITY. Do not pass --max-priority unless the user asked for a specific threshold. Built-in default is P1 when neither is set. P0 means issues worth blocking the current change because they materially break the normal flow, outcome, or safety boundary; P1 means real defects in the changed code that should be fixed before shipping even if the main flow still works. Reviewers rate the same defect P0 or P1 inconsistently, so a P0-only threshold silently drops real bugs. Wider thresholds include those findings plus the extra priorities. Treat helper output at the configured threshold as the review result; do not drop in-threshold findings just because they are not P0.
• Treat review output as advisory. Never blindly apply it.
• The subagent engine is a non-independent review: the reviewer is the host agent, sharing the author model and context. Prefer codex/claude/pi whenever one is available, and keep the reviewer independence: none (subagent shares the author model/context) line in the final report.
• Close the feedback loop: after verifying findings, record each accepted/rejected decision with --record-dispositions (see Review History And Retrospective) so reviewer quality is measurable over time.
• Verify every finding by reading the real code path and adjacent files.
• Read dependency docs/source/types when the finding depends on external behavior.
• Reject unrealistic edge cases, speculative risks, unrelated rewrites, and fixes that over-complicate the codebase.
• Prefer root-cause fixes at the right ownership boundary. A coherent refactor is appropriate when it removes the bug class, duplicate policy, stale paths, or ownership confusion; do not default to a symptom patch.
• When an accepted finding exposes a bug class or repeated pattern, inspect its owner and relevant sibling implementations before fixing.
• Fix the same bug class across its owner-boundary neighborhood when practical; stop at unrelated invariants, different owners, and unapproved contract changes.
• Keep going until structured review returns no accepted/actionable findings only while the work remains inside the authorized architectural and task scope.
• If a review-triggered fix changes code, rerun focused tests and rerun the structured review helper.
• For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk.
• Never switch or override the requested review engine/model except for the documented Codex Sol-to-Terra account-access fallback, the documented pi access-only fallback-model retry, and a recorded Codex usage-limit cooldown. Capacity and unrelated failures keep the same engine/model. A Codex usage-limit failure records a fixed cooldown (default 1 hour, AUTOREVIEW_CODEX_COOLDOWN_HOURS) and later runs skip Codex in favor of Claude instead of waiting on reset. Do not retry Codex during that window. --ignore-codex-cooldown forces Codex. When the engine was never requested (no --engine, no AUTOREVIEW_ENGINE) and the default or cooldown-substituted CLI is not installed, the helper switches to the subagent engine and says so; an explicitly requested engine is still never replaced. --no-engine-fallback or AUTOREVIEW_NO_ENGINE_FALLBACK=1 disables that switch.
• Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search.
• Treat heartbeat lines like review still running: ... elapsed=... pid=... as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass --stream-engine-output when live engine text is useful; Codex and Claude filter tool/file chatter, other runnable engines pass raw output through.
• Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish.
• If the repository changes while a bundle is being built or reviewed, keep the captured bundle's report, warn that it describes that snapshot, and preserve the concurrent changes. Do not discard an otherwise valid code review solely because another actor edited the worktree; rerun later when a report for the newer snapshot is needed.
• Tools are useful in review mode. Codex receives the validated bundle in an empty workspace so ignored files and linked-worktree metadata remain unreadable; web search stays available for dependency contracts and upstream docs. BB receives the bundle as an attachment in a temporary workspace outside the reviewed repository, but BB does not expose a per-thread host-read boundary; reserve it for trusted changes.
• Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check.
• Reviewer subprocesses preserve engine authentication and non-credentialed proxy variables needed by headless or restricted-network environments while stripping process-injection, Git override, and credentialed proxy values.
• TruffleHog is intentionally outside autoreview's default engine path. Run the standalone scripts/trufflehog-preflight command for an explicit pre-commit, push, CI, or external-review credential gate; it scans temporary snapshots of the exact added, modified, or deleted content and uses TruffleHog's low-false-positive verified,unknown policy. One-to-one renames whose blobs are byte-identical are omitted because they introduce or remove no bytes; copies, ambiguous many-path moves, and renamed files with content changes remain scanned. The standalone preflight does not classify arbitrary password-like strings or rescan unchanged history. Autoreview still redacts locally recognized secret-like values when building its review bundle, and repositories should run TruffleHog in pull-request CI as a backup. Install TruffleHog using its official platform-neutral instructions; the standalone command fails with that link when the binary is unavailable and never auto-installs it. Review bundles still omit security-sensitive paths or files, and explicit prompt and dataset inputs remain checked before engine invocation. Safe large diffs are sent as one pass while they fit the aggregate prompt limit, then partitioned into complete bounded passes without truncation.
• For regression provenance, keep roles separate: blamed code author, blamed PR author, PR merger/committer, current PR author, and PR/date. If no blamed PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding.
• If the blamed PR was merged by clawsweeper[bot] or another automation, identify the human trigger when practical. Check timeline/comments first; if rate-limited, use gitcrawl/cache or public PR HTML. Look for maintainer commands such as @clawsweeper automerge, /landpr, or labels/status comments that armed automerge. Report automerge triggered by @login; if not found, say trigger unknown.
• Do not invoke built-in codex review, nested reviewers, or reviewer panels from inside the review. The helper builds one validated bundle, calls the selected engine once for normal inputs or once per complete bounded chunk for oversized inputs, validates the structured results, and stops.
• Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
• Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse.
• Multi-reviewer panels are opt-in only. Use them when explicitly requested or when risk justifies the extra spend; the main agent still verifies every accepted finding before fixing.
• If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
• If gh/Gitcrawl reports database disk image is malformed, run gitcrawl doctor --json once to let the portable cache repair before retrying review; do not bypass the shim unless repair fails and freshness requires live GitHub.
• If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run gitcrawl doctor --json and inspect source_db_health, runtime_db_health, and portable_store_status before falling back to live GitHub.
• Do not push just to review. Push only when the user requested push/ship/PR update.