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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: momentmaker
• Source: momentmaker/kaijutsu
• License: MIT
• Homepage: https://kaijutsu.dev/

Install and usage instructions live in the source repository linked above.