/polish-code

name: polish-code
description: "Stage, format, lint, test, review, smoke test, and re-run until stable. Use when the user asks to \"polish code\", \"refine code\", \"iterate on code quality\", \"review loop\", or \"run the polish loop\"."

Polish Code

Task Tracking

At the start of every invocation (including re-runs from Step 7), use `TaskCreate` to create a task for each step:

1. Run `/stage` skill 2. Run `/run-checks` skill 3. Run `/review-code` skill 4. Run `/evaluate-findings` skill 5. Run `/apply-findings` skill 6. Run `/smoke-test` skill 7. Re-run `/polish-code` skill if changed

Loop State

Loop state lives in a ledger at `.turbo/loops/polish-code-<label>-<tag>.md`. The label is the governing plan's slug when one is in context, otherwise the current branch name with non-alphanumerics replaced by hyphens. The tag is the output of `head -c 4 /dev/urandom | xxd -p`, minted once when the loop starts. The ledger records `Branch:` (the unmodified branch name, or `(detached)`), `Plan:` when a plan governs, a one-line purpose, and per iteration an `Iteration <N>: <state>` line, its verdicts, and Step 7's classification. A ledger that exists belongs to an active loop.

At the start of every invocation, before `/stage` runs in Step 1, resolve the ledger:

• **Carried path:** this invocation was passed a ledger path, by the re-run Step 7 starts or by a handoff. Continue that ledger. A carried path whose file no longer exists falls through to discovery. Take a carried path only from those two sources, never from a task another invocation left behind.
• **Discovery:** with nothing carried, list the untracked ledgers in `.turbo/loops/` whose name starts with `polish-code-` and whose `Branch:` is the current branch. Also list every untracked `polish-code-` ledger there that holds a `Pending smoke-test baseline`, on any branch. Output each one's purpose, last iteration and its state, and file modification time as text. For a pending baseline, add its differing paths, found by items 1-3 of the pending-baseline reconciliation. When any are listed, use `AskUserQuestion` to offer resuming a ledger, discarding a ledger, or starting fresh, naming the ledger in each resume and discard option; when more ledgers are listed than options fit, first ask which ledger to act on, offering the most recently modified ones and leaving the rest to the free-text answer. Starting fresh mints a new path and deletes nothing. Delete a ledger named for discarding once any pending baseline in it is reconciled, then run discovery again. Reconciling a pending baseline right after discovery reuses the capture and differences discovery produced.
• **Fresh:** mint a new path and write the ledger with `Iteration 1: open`.

Once the ledger resolves, use `TaskUpdate` to write its path into this invocation's Step 7 task description. After a compaction, this invocation reads its ledger path back from that task.

**Iteration state.** The current iteration's state line reads `open` until Step 7 reaches a gate, `awaiting <gate>` while Step 7 waits on the user at one (the in-place round, the skip permission, the hard cap, or the context-signal question, recorded with the gate it wraps), and `classified` once Step 7 has settled whether another iteration runs. On a continued ledger, read the last iteration's state:

• `classified`: carry out the decision recorded with the classification. On another iteration, this invocation is the next one: append `Iteration <N+1>: open`. On an escalation to `/consult-oracle`, resume that escalation, and once the oracle answers, record the decision its answer leads to (another iteration, or a stop that deletes the ledger) in place of the escalation.
• `awaiting <gate>`: the interrupted iteration already ran Steps 1-6, so mark this invocation's Step 1-6 tasks completed. Ask that gate again before anything else; for the context-signal question, ask only the gate it wraps, since this session starts with fresh context. When it wrapped an automatic re-run, offer run another iteration, marked recommended, or stop iterating; when it wrapped a run that edited nothing, the loop has ended, so delete the ledger. Then proceed by the answer as Step 7 does.
• `open`: the iteration was interrupted. Rerun it under its own number from Step 1. The verdicts it already recorded stand: Step 4 keeps them rather than recording them again.

A compaction in flight is not a resume: this invocation continues its own iteration. A continued ledger supplies the most recent `/review-code` diff command it records, when it records one, in place of Step 3's default.

**Pending smoke-test baseline.** This entry means an iteration was interrupted between delegating the smoke test and verifying the tree. Reconcile it before Step 1 whenever a resumed or discarded ledger holds one, so Step 1 does not stage what the interrupted subagent left behind. The entry holds a state from `${CLAUDE_SKILL_DIR}/scripts/checkout-snapshot.sh`:

1. Run `checkout-snapshot.sh check` with that state. When it prints `LOST`, `git gc` has pruned the snapshot; when it prints `INVALID`, the state names a HEAD ref outside the local branches or paths git never checks out. Either way, report it, write nothing, and clear the entry once the report is out. 2. Run `checkout-snapshot.sh capture` for the current state. 3. List what differs between the two: the paths `git diff --name-only --no-renames` reports between their index trees and between their raw trees, and any difference in REF or COMMIT. 4. When nothing differs, clear the entry and continue. 5. Otherwise output the differences as text, then use `AskUserQuestion` to offer restoring the pending baseline or keeping the current state. Restoring runs `checkout-snapshot.sh restore` with the pending state; record the `UNDO` line and any `MOVED` lines it prints in the ledger as `Post-run state`, as Step 6 does. Then run `verify` and handle its result as Step 6's tree verification does. Keeping clears t