Polish Code

Polish Code

Task Tracking

At the start of every invocation (including re-runs from Step 7), use update_plan to track each step, restating any remaining steps of a parent workflow alongside them:

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 at .turbo/loops/<slug>.md — slug from the governing plan when one is in context, otherwise the current branch name with non-alphanumerics replaced by hyphens. At the start of every invocation, read the ledger if it exists.

• Fresh loop (no ledger, or its Status: line is closed): write a fresh ledger with Status: active, then attempt create_goal with the objective: "Run the $polish-code loop on <scope> until converged: a run with no changes, an in-place-only round, or remaining findings that do not justify another re-run. Loop state: .turbo/loops/<slug>.md; re-read it after any context compaction and do not re-adjudicate findings it records as rejected, escalated, or applied with a narrowed remedy. Mark this goal complete when the loop converges." If an unfinished goal already exists, an outer workflow owns it; continue without creating one.
• Continuing loop (Status: active): this invocation is the iteration after the last one the ledger records, whether a Step 7 re-run or a resumption after an interruption. Continue from the recorded state, using the most recent $review-code diff command the ledger records, when it records one, in place of Step 3's default. A Pending smoke-test baseline entry means a previous iteration was interrupted between delegating the smoke test and verifying the tree: reconcile the tree against that entry and clear it before Step 1, so Step 1 does not stage what the interrupted sub-agent left behind. If no unfinished goal exists, attempt create_goal with the same objective as a fresh loop.
• During each iteration: have the ledger path in context when Steps 3 and 4 run so recorded verdicts are honored. Append each applied, rejected, and escalated verdict with its reason to the ledger under the iteration number as Steps 4-6 reach it, along with the user's resolution of an escalated one. After Step 7's classification, append the classification and, when the run goes into another iteration, that iteration's $review-code diff command with the tree ID filled in. For an escalated verdict the user resolved, the reason attributes to the user only what they decided; the details you picked while implementing it stay open to review.
• Convergence stop (a run with no changes, an in-place-only round, or a further re-run judged pointless): set Status: closed; if this loop created the goal, mark it complete with update_goal. An inherited goal stays active for the outer workflow. A halt on an unresolved failure leaves Status: active and the goal untouched, so the next invocation resumes the recorded state.

Step 1: Run $stage Skill

Run the $stage skill.

Step 2: Run $run-checks Skill

Run the $run-checks skill.

Stage all changes made in this step before continuing.

Step 3: Run $review-code Skill

Run the $review-code skill on the staged changes. The diff command is git diff --cached.

Step 4: Run $evaluate-findings Skill

Run the $evaluate-findings skill on the results from Step 3.

Step 5: Run $apply-findings Skill

Record the staged tree with git write-tree before applying anything, and write the tree ID it prints to the ledger as Review tree, replacing any entry already there.

Run the $apply-findings skill on the evaluated results.

Append any fix whose remedy you deliberately narrowed to the ledger as you make it, naming what the remedy covered and what it left, so Step 7 carries it forward without reconstructing the decision later.

When a fix ships with a regression test, confirm the test fails with the fix reverted, then restore the fix. When that test's outcome depends on the order of concurrent events, also run it many times over with the fix in place. Find what caused a failure on any of those runs, typically an ordering defect in the code or a missing synchronization point in the test, and fix it, then repeat both checks before this step closes.

Stage the fix immediately before mutating it (git add <file>), so git checkout -- <file> restores it exactly from the index. A file staged in an earlier step has an index copy older than the current edits, and restoring reverts them. Stage only the files about to be mutated: a broader restore point sweeps in working-tree changes the project may require stay uncommitted. When one also carries unrelated changes, write git diff <file> to a patch file, back the unrelated changes out of it (delete their + lines and turn their - lines into context lines), and stage it with git apply --cached --recount <patch>. Its index copy then lacks those changes, so copy that file aside before mutating it and restore it from the copy instead of the index. Each mutation edits the shared working tree in place, so hold anything that reads or builds that tree until the mutation is restored.

Before running the tests against a mutation, confirm it landed: git diff -- <file> shows the intended change against the index for each mutated file. An edit whose match pattern missed leaves the file untouched. Count a mutation as caught only when the test run reports a failing test, not when the mutation command or a step chained before the tests exited nonzero.

When the fixed code combines several signals, also apply the plausible rewrites a maintainer might reach for — reordering the signals, substituting a fallback chain for a conjunction, dropping a term that looks redundant — and confirm each fails at least one test, then restore the fixed code. A rewrite that passes every test while changing behavior on some input means the tests pin the examples rather than the invariant; add the test that distinguishes it. When the fix guards against an unbounded loop or wait, bound the test itself so that reverting the fix fails rather than hangs: cap the iteration count for a loop; enforce a deadline for a wait. A deadline inside the test can depend on the test cooperating, so also run each such mutation under a timeout enforced from outside the test process.

When the fix changes when, whether, or how often a mechanism runs, mutate the changed line and run the whole affected suite, not only the test written for this fix: a fix can disarm tests that already existed, and those keep passing. Concentrate on the tests whose pass condition is an absence, and establish for each one that still passes whether it passes for the reason it did before. Those tests cannot distinguish a guard that rejected the work from a mechanism that never ran.

A test whose pass condition is an absence needs an assertion establishing the mechanism was reachable. Place that arming assertion before anything that can consume the state it reads. Placed after, the assertion holds whether or not the guard exists, and the test looks rigorous while pinning nothing.

A test that asserts only the direction of a numeric change passes on any movement of the right sign, including rounding noise or drift the fix did not cause. Assert the expected size of the change instead.

When the test still passes with the fix reverted, suspect the mutation before the test: confirm it reaches the branch under test and reproduces the original behavior rather than a third one. Name the branch under test and the original behavior it reproduces before running the mutation, then re-read the mutated lines. A mutation that lands a statement away from that branch also changes paths the fix never touched, and the resulting failure is indistinguishable from a caught mutation.

When the mutation is faithful and the test still passes, the test cannot observe the defect. Determine which of four shapes applies before reworking the test's setup:

• The assertion inspects output that is identical whether or not the defect is present. Assert on the mechanism itself rather than on the output it produces: teardown, cancellation, deduplication, and ran-only-once fixes leave no trace there.
• The inputs the test drives land the same way under the fixed value and the mutated one. When the fix seeds an initial value, drive an input on the far side of that seed; a test that only advances past it never observes the seed.
• An earlier guard against the same condition catches first, leaving the guard under test unreachable. Construct the ordering that reaches the later guard specifically. A defense-in-depth guard is reachable only through the window its predecessor does not cover, and an end-to-end exercise of the operation misses it systematically.
• The entry surface the test drives is itself closed for the window the guard covers, so no input the test can send reaches the guard. Where the earlier shape puts a predecessor in the code path, this one puts the block ahead of it: when the fix guards a repeat invocation, a busy or pending state on that affordance refuses the repeat before the guard sees it, and the test passes for the wrong reason. Drive an entry point that carries no such state instead.

A test that genuinely cannot be made to fail does not pin the behavior; say so rather than counting it as coverage.

After every mutation in this step, re-run whatever that mutation was checked against and confirm it passes again and the test command itself exits 0, not a filter piped after it, before reporting the result. A clean git status looks identical whether the fix was restored or deleted. A run that a mutation made fail can leave behind what a passing run cleans up, such as temporary files and spawned processes. Before that re-run, clear what the failed run left, identified by what the run itself started or named. Leave anything whose origin that does not establish, and name it when reporting the result.

A project command run to verify a fix writes to the shared tree the same way a mutation does. Establish whether it writes tracked files before running it, and read git status --short afterward: revert what it wrote, so files it regenerated are not swept into the changeset by the staging below.

Stage all changes made in this step before continuing.

Step 6: Run $smoke-test Skill

Capture git status --short, git diff --cached | git hash-object --stdin, git diff | git hash-object --stdin, and git symbolic-ref --short -q HEAD before spawning.

When the ledger records a Smoke-tested baseline, compare it against the first three outputs and git rev-parse HEAD. When all four match, report the result recorded with that baseline as carried forward and close this step, running neither the $smoke-test skill nor a test run. On any difference, or with no such entry, continue.

Run the $smoke-test skill to produce the smoke test plan.

Record all four captured outputs in the ledger as Pending smoke-test baseline, replacing any entry already there.

Spawn a Codex sub-agent with inherited model defaults to execute the test plan. Pass the plan and the diff command (git diff --cached) into the sub-agent's context, and instruct it to read and follow $test-run-rules from the installed skill directory before executing the plan. State in its context that the writes the plan's Setup contract authorizes are already approved, and that any write outside that enumeration leaves its scenario blocked.

Verify the tree: re-run all four commands when the sub-agent returns, including when it terminates early or reports incomplete results. Compare against Pending smoke-test baseline. Delete what the sub-agent created, revert what it modified or staged, and return HEAD to the captured branch, leaving everything that baseline already showed untouched. Clear the entry once the tree matches.

If any test fails, fix the issues and stage the fixes. When every planned test passed and the verification above found nothing to delete or revert, record the Smoke-tested baseline in the ledger, replacing any entry already there: the first three captured outputs, git rev-parse HEAD, and the result the run reported.