/polish-new

name: polish-new
description: Pre-release code review that converges - parallel review agents sized to the diff, findings validated against evidence in a run ledger, fixes on approval, then re-reviews its own fixes until a round warrants no edits. Run on /polish-new.
metadata:
  version: "0.1.2"
  categories: "development"
  topics: "code-review, linting, refactoring, pre-release, diff-review"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/polish-new
    emoji: "✨"
argument-hint: "[base-ref]"

Pre-Release Polish

A review is finished when a review of its own fixes warrants no further edits - not when the fixes are written, not when checks pass. Evidence beats judgment: a finding that cannot be reproduced from its own citations does not survive. The fix pass is where the next round's defects come from, so it gets reviewed like any other code. Findings live in files, not in this conversation - context can be compacted away mid-run; if you are resuming after a compaction or interruption, re-read `ledger.md` and the saved agent reports before continuing. They are the source of truth, not the summary.

A base ref may be passed as an argument; Phase 2 uses it for scope.

Phase 0: Orient

Work in the repository under review - it may be a worktree, not the current directory. Establish state there:

git rev-parse --abbrev-ref HEAD
git status --short
git diff --stat

Create the run directory `.agents/polish/<YYMM-DD-HHMM>-<slug>/` with an `agents/` subdirectory, and start `ledger.md` recording the reviewed sha (`git rev-parse HEAD`) and, as they launch, one row per agent (lens, shard, output file, launch time, plus any run identifier the harness exposes). Base ref and diff stat are backfilled at the end of Phase 2. Findings get ledger rows as reports arrive, not later.

If `.agents/` is not already ignored, add `.agents/polish/` to the project's ignore file - run artifacts are working state, never committed.

The reviewed sha makes this review a certificate about one snapshot. Anything committed after it is unreviewed; a later run scopes to `<reviewed-sha>..HEAD`.

Phase 1: Automated Checks

Run the project's lint + type-check command. Check CLAUDE.md (or the equivalent project instructions) for the correct validation command - commonly `pnpm check`, `just check`, `cargo clippy`, `uv run ruff check`. If none is documented, ask.

If checks fail: fix all errors, re-run until clean, then continue. Do not start the review against a failing gate. When a failure predates the diff (it reproduces on the base ref), still fix it - but record it in the ledger as `pre-existing gate failure, fixed` and surface it in the report.

Phase 2: Map

Resolve the base ref: the argument if one was passed; else the repository's default branch (`git symbolic-ref refs/remotes/origin/HEAD`, falling back to whichever of `main`/`master` exists); if neither resolves or there is no merge base (shallow clone, detached HEAD), say so and ask the user for a base.

Scope is a **union**: `<base>...HEAD`, plus staged and unstaged changes, plus untracked (`??`) source files. The reviewed-sha certificate must be true of the whole union. If the work under review was committed this session, the branch side narrows to those commits. A staged change that references an untracked file is itself a finding: without the file, fresh checkouts and CI break. If nothing changed at all, report "nothing to review" and stop.

Write the diff to a file in the run directory. `git diff` does not emit untracked files - append each one via `git diff --no-index /dev/null <path>`, and include untracked paths in the changed-file list handed to agents. Exclude lockfiles and generated outputs (`Cargo.lock`, `pnpm-lock.yaml`, `*.snap`, generated bindings) - but never a plan or spec document the branch implements: that is review input. For moved or rewritten code, note the prior version (`git show <ref>:<path>`) for agents to compare behavior against. Backfill the ledger header: base ref, diff stat.

Read the diff's **structure**, not every line: which subsystems it touches and which control flows it changes. Then produce the shard plan and arm the conditional lenses.

**The shard plan.** If the diff is tiny (under ~50 changed lines), skip the finder agents and review all lenses yourself, reading every changed line - the fast path skips ONLY the finder fan-out; the run directory, ledger, evidence standard for your own findings, skeptics on your confirmed correctness findings, report, approval gate, fix pass, and fix review all still apply. Otherwise one agent per lens. When a lens's share would exceed roughly 1500 lines of diff, split that lens across shards - enumerate the lens's natural units and assign each agent a few, drawing boundaries so control flows stay intact:

| Lens | Shard unit - enumerate these to shard | |---|---| | Cleanliness | files - the only genuinely local lens | | Efficiency | hot paths (per-frame/per-request/per-render/per-log-line/per-CI-run work) and shared resources (memory limits, locks, caches, stores, pools, declared timeouts), each traced end to end | | Design & Reuse | subsystems, with whole-diff visibility | | Side-Effect Gating | side-effect flows - each costly or irreversible action the diff introduces or relocates (charges, writes, deletes, mutating external calls, notifications), traced entry point to effect |

A shard assigns **accountability, not visibility**: every agent gets the full diff and may read anything in the repository; it is answerable for complete coverage of its shard.

**The conditional lenses.** Arm Control Verification if the diff touches a security control (credentials, auth, permissions, payments, sandboxing, input validation at a trust boundary). Arm Plan Conformance if a plan or spec document for this branch exists.

Phase 3: Find

Launch all agents concurrently. Every agent this skill spawns - finder, skeptic, dive, fix-review - receives the Agen