polish

name	polish
description	Iteratively review and simplify uncommitted changes until clean or stuck. Use when the user asks to polish, clean up, or iteratively improve uncommitted code changes.

polish — review + simplify loop

Looped polish pass over uncommitted changes (staged + unstaged). Each iteration: review the diff for problems, apply safe simplifications, then re-review. Exit when there are zero critical/error findings and nothing left to simplify, or when stuck or the iteration cap is hit.

Never auto-commits. Never pushes.

Input

Optional max-iterations (positive integer, default 5). "polish 3" caps at 3.

Phase 1 — Scope

Capture the edit surface once, at the start:

git diff HEAD --name-only

• Empty (no uncommitted changes): ask the user "No uncommitted changes. Polish the last commit instead?" If no, stop. If yes, ask whether to amend the last commit or make a new commit, remember the answer, and set the edit surface to git diff HEAD~1 HEAD --name-only.
• Non-empty: the edit surface is that file list.

Record a baseline for the scope-drift check:

git diff HEAD --stat
git diff HEAD | shasum -a 256

Print a short header: files changed, max iterations, exit gate.

Phase 2 — Loop

For each iteration up to max-iterations:

A. Review. Read the diff for the edit-surface files and collect findings across four lenses: security, performance, quality (complexity, maintainability, naming), and architecture (layering, coupling, dependency direction). Give each finding a severity (critical / error / warning), a file:line, and a short title. Build a stable identity per finding: category|file:line|title.

B. Decide.

State	Condition	Action
Pass	0 critical and 0 error, and the prior simplify pass left nothing to do	stop → Phase 3
Stuck	iteration > 1 and the finding set equals the previous iteration's	stop → report
Max-out	last iteration reached without passing	stop → report
Progressing	otherwise	continue to C

C. Simplify. Apply safe simplifications to the edit-surface files, preserving behavior exactly. Prioritize the findings, then opportunistic clarity (naming, dead code, nested ternaries, obvious-comment removal) per project standards. Hard constraints:

• Only edit files in the edit surface.
• Do not create new files.
• Do not touch files outside the surface, even to add an import.
• Preserve all public APIs and runtime behavior.

Track what you could not fix and why — that feeds the Pass gate next iteration.

D. Scope-drift check. Run git diff HEAD --name-only again. If any file appears that was not in the edit surface, abort the loop, report the offending paths, and stop. Do not revert.

Phase 3 — Sanity (Pass only)

Only if the loop exited via Pass. Detect the toolchain and run, in order: tests, lint, typecheck, format. Prefer the package manager the repo already uses. A failing gate demotes the result to "Pass (with gate failures)" — do not loop again, just surface it.

Phase 4 — Report

One short block (max ~20 lines): exit state, iterations used, findings start vs end, files changed since baseline, scope drift, sanity-gate results, top remaining findings, and next steps. End with the reminder that polish does not commit — the user commits when ready (amend or new, per the Phase 1 answer).

Guardrails

• The edit surface is sacred — only those files may change.
• No auto-commit, no auto-push.
• Hard iteration cap — never exceed max-iterations.
• Stop early when the same findings recur (stuck).
• The simplifier must not change public APIs or runtime behavior.