# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-momentmaker-kaijutsu-polish`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [momentmaker](https://agentstack.voostack.com/s/momentmaker)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [momentmaker](https://github.com/momentmaker)
- **Source:** https://github.com/momentmaker/kaijutsu/tree/main/skills/core/polish
- **Website:** https://kaijutsu.dev/

## Install

```sh
agentstack add skill-momentmaker-kaijutsu-polish
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/momentmaker)
- **Source:** [momentmaker/kaijutsu](https://github.com/momentmaker/kaijutsu)
- **License:** MIT
- **Homepage:** https://kaijutsu.dev/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-momentmaker-kaijutsu-polish
- Seller: https://agentstack.voostack.com/s/momentmaker
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.