# Polish > Automated post-implementation review-and-fix loop. Use after completing a feature or implementation plan to find and fix issues across multiple passes until convergence. Invoke with /polish. Composes blunder-hunt for the review pass, convergence-detect for the stop condition, and deslop for any user-facing prose at the end. - Skill: `momentmaker/polish` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add momentmaker/polish` - Raw SKILL.md: https://api.skillmd.com/api/skills/momentmaker/polish/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: momentmaker (https://skillmd.com/u/momentmaker) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/momentmaker/polish --- # polish Loops until clean. Each pass: review the diff, fix everything found, re-run tests/linters. Stop when `convergence-detect` says no new signal is appearing. This skill composes: - `blunder-hunt` for the review (multi-pass adversarial critique) - `convergence-detect` for the stop condition (smarter than "ran N rounds") - `verification-before-completion` for the hard test/build/lint gate AFTER convergence (convergence ≠ correctness) - `deslop` for any user-facing prose touched in the diff ## Step 0: Scope Determine what was implemented: - Read any active implementation plan if it exists - `git diff master...HEAD --stat` (or `--cached --stat` / `--stat` if on master) - Identify all files in the change set ## Step 1-N: Review-Fix Passes Cap at 4 passes. Stop early when `convergence-detect` says converged. For each pass, alternate two lenses: ### Lens A — Random Code Exploration (odd passes: 1, 3) Traverse the codebase semi-randomly: 1. Pick 5 files in the diff at random 2. Read each in full, not just the diff hunks 3. Look for: dead code from refactoring, leftover debug statements, missing error handling at system boundaries, security issues, race conditions, missing tests for new paths 4. For each finding: severity + file:line + description ### Lens B — Cross-Agent Integration Review (even passes: 2, 4) Look at how pieces fit together: 1. List the public-API surface added or changed in the diff 2. Find every call site of those APIs (in the diff and outside) 3. Verify: contracts honored, error paths handled by callers, no silent type narrowing, no swallowed errors 4. For each finding: severity + file:line + description ### Apply blunder-hunt to each pass Run `blunder-hunt` with the pass's lens on the in-scope files. The primitive handles the lie-to-them pressure and the dedup. Polish just consumes the output. ### Parallel pass-runners (when supported) For a single pass with K lenses, compose `dispatch-parallel`: spawn one subagent per lens, run all in parallel, collect findings. Wall-time savings are large on big diffs. Each subagent gets the same diff but a different lens prompt; synthesis dedupes findings that surface in 2+ subagents. If the platform doesn't support parallel subagents, fall back to sequential — same lenses, same dedup, just slower. ### Fix Phase After each pass, fix every finding (not just critical). Run the project's test/lint commands. If a fix breaks something, fix that too — count as part of the same pass. ### Convergence check After pass 3 — once you have at least three rounds of findings — invoke `convergence-detect`. If it returns CONVERGED, stop. Otherwise continue to pass 4 (the cap). ## Step F: Final deslop Before declaring done, scan the diff for user-facing prose: README sections, commit messages, doc strings, error messages shown to humans, CLI help text. Run `deslop` on each. Skip code comments unless the diff specifically reworked them. ## Step V: Verification gate (HARD STOP) After convergence + deslop, BEFORE emitting "polish complete", run `verification-before-completion`. The convergence-detect signal means "no new findings in the last pass". It does NOT mean "the code still compiles + tests still pass". Both can be true OR false independently. The primitive enforces: 1. Identify the verification commands for this codebase (test runner, linter, type-checker, build). 2. Run them ALL fresh, in this turn (not "I ran them earlier"). 3. Read full output + exit codes. 4. If anything fails → state truth, fix, re-run from Step 1 (the convergence loop). 5. If all pass → emit the polish-complete claim WITH the evidence (commands ran + N/N pass). Never declare polish-complete on vibes. The evidence template lives in `verification-before-completion`'s SKILL.md. ## Step Final: Summary ``` ## Polish Summary - Passes completed: - Stop reason: - Issues found: ( critical, issue, minor) - Issues fixed: - Tests: - Deslop edits: - Status: remaining items> ``` If items remain after the cap, list them for the user. ## Optional: branch-protected mode For long-running polish loops on critical code, optionally commit each pass as a separate commit on a `polish/` branch: 1. Before pass 1, create branch `polish/` off the current HEAD 2. After each pass's fix phase, commit with message `polish: pass N — ` 3. If a later pass introduces a regression, `git bisect` over the polish commits identifies the culprit fix 4. At the end, optionally squash before merging back to the working branch This trades commit-history noise for an auditable trail. Useful for high-stakes refactors; overkill for small fixes. ## Hard rules - DO fix issues immediately — don't just report them - DO run tests after each fix pass - DO stop when convergence-detect says converged, even before the cap - DO refuse to declare done if tests are failing at any point in any pass — hard test gate (enforced by `verification-before-completion`'s gate at Step V) - DO commit after polish (ask user first) - DON'T gold-plate. Real issues only, no style refactors - DON'T add features. Correctness only - DON'T count cosmetic preferences as issues unless they violate project conventions - DON'T silently revert decisions the author made — if you disagree, raise it as a finding for the user to weigh in - DON'T parallelize the *fix phase*. Parallel review is fine; parallel writes to the same files = chaos.