/polish

name: polish
description: Pre-release code review - runs lint/type checks, launches parallel review agents (cleanliness, design, efficiency, side-effect gating) on the diff, validates findings, and fixes with approval. Use before committing, pushing, or releasing changes.
metadata:
  version: "2.4.1"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/polish
    emoji: "✨"
disable-model-invocation: true
argument-hint: "[base-ref]"
allowed-tools: "Bash(git diff *), Bash(git show *), Bash(git status *), Bash(git rev-parse *), Bash(git log *)"

Pre-Release Polish

Repository state:

git rev-parse --abbrev-ref HEAD
git status --short
git diff --stat 2>/dev/null | tail -1

Base ref argument (optional): $ARGUMENTS

Rules

• Read every changed file fully before reviewing - never assess code you haven't opened
• Only flag real issues, not style preferences already handled by the formatter
• Do NOT add comments, docstrings, or type annotations to code that doesn't have them
• Distinguish legitimate operational logging (`logger.info`, `logger.error`) from debug leftovers (`console.log`, `console.debug`)
• When fixing, make minimal targeted edits - don't refactor surrounding code
• Only flag issues in changed/added lines, not pre-existing code
• Reuse suggestions must point to a specific existing function/utility in the codebase, not hypothetical "you could extract this"
• Do not flag efficiency on cold paths, one-time setup code, or scripts that run once

Phase 1: Automated Checks

Run the project's lint + type-check command. Check CLAUDE.md for the correct validation command (commonly `pnpm check`, `just check`, `cargo clippy`, `uv run ruff check`, etc.).

If checks fail: 1. Fix all errors 2. Re-run checks until clean 3. Then proceed to Phase 2

If no validation command is found in CLAUDE.md, ask the user what to run.

Phase 2: Diff Analysis

Determine what changed: 1. Check for uncommitted changes: `git diff` + `git diff --cached` 2. Check for untracked (`??`) files in `git status --short`. Include new untracked source files in the review. A staged change that references an untracked file (a new module, benchmark target, or test) is itself a finding: if the change lands without the file, fresh checkouts and CI break on the missing reference 3. If a base ref was passed as an argument, diff against it: `git diff <base-ref>...HEAD` 4. If no uncommitted changes and no base ref, diff against main: `git diff main...HEAD`. If the work under review was already committed this session, scope the review to those session commits rather than the whole branch 5. If no changes at all, report "nothing to review" and stop

Exclude lockfiles and generated files from the review (`Cargo.lock`, `pnpm-lock.yaml`, `package-lock.json`, `*.snap`, generated bindings) - they are outputs, not authored code.

Read every changed file fully. Understand what each change does and why.

When a change relocates or rewrites an existing code path (a moved file, a handler split into middleware, a renamed/replaced function), open the prior version - the file it moved from, or `git show <ref>:<path>` for a deleted/renamed file - and compare behavior, not just lines. Note any dropped validation, reordered side-effects, or removed guards; pass those to the agents.

Phase 3: Parallel Review

Write the diff to a scratchpad file. Use the Agent tool to launch all four agents concurrently in a single message. Pass each agent the diff file path and the list of changed files so it has the complete context - do not inline a large diff into four prompts.

Enrich each agent's prompt with:

• Relevant project constraints from CLAUDE.md (performance assumptions, logging conventions, platform quirks) so findings are domain-correct
• Known-intentional patterns in the diff that would otherwise be flagged (e.g. a deliberate `console.log` in a test-skip path matching project convention) so agents don't return known false positives

**Small-diff fast path**: if the diff is tiny (roughly under 50 changed lines), skip the agent fan-out and review all four lenses below directly yourself, reading every changed line in full. All later phases still apply.

Agent 1: Cleanliness

Fast, mechanical, high-confidence. Looks for junk that should be removed.

• **Debug leftovers**: `console.log`, `console.debug`, `console.warn` added during development; temporary debug variables, hardcoded test values. NOT structured logger calls (`logger.info`, `logger.error`, `c.var.logger`)
• **AI slop**: comments explaining obvious code ("// increment counter", "// return the result") - flag each such comment individually, even if the code it describes is also flagged under another category; JSDoc on internal/private functions that aren't part of a public API; verbose docstrings on simple helpers; `TODO`/`FIXME`/`HACK` markers left by Claude (not by the user); unnecessary type annotations where the language infers correctly; emoji in code or comments (unless the project uses them)
• **Non-ASCII punctuation**: em-dashes, smart quotes, or other unicode punctuation introduced in changed lines (unless the project uses them). Plain-text grep over a diff can miss multi-byte characters - scan the changed files byte-aware, e.g. `rg -n '[\x{2010}-\x{2015}\x{2018}-\x{201F}]'`
• **Dead code**: unreferenced functions, variables, types; commented-out code blocks (git has history); unused function parameters (unless required by interface/callback signature)
• **Unused imports**: imports added but never referenced, imports left behind after refactoring (linter catches most - verify edge cases)
• **Hardcoded values**: magic numbers or strings that should be in constants; URLs, prices, limits that belong in config. NOT obvious constants like `0`, `1`, `true`, HTTP status codes

Agent 2: Design & Reuse

Requires codebase exploration beyond the diff. Looks for structural and design issues.

• **Reuse opportunities**: search the codebase