/refine-plan

name: refine-plan
description: "Iteratively review and revise a plan until no new findings survive evaluation. Use when the user asks to \"refine the plan\", \"iterate on the plan\", \"tighten the plan\", or \"improve the plan\"."

Refine Plan

Loop the review pipeline over a plan until no new findings are accepted. Writes back to the plan file in place.

Task Tracking

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

1. Resolve the plan 2. Run `/review-plan` skill 3. Run `/evaluate-findings` skill 4. Run `/apply-findings` skill 5. Re-run `/refine-plan` skill if changed

Step 1: Resolve the Plan

1. **Explicit path** — use it 2. **Explicit slug** — resolve to `.turbo/plans/<slug>.md` 3. **Single file** — Glob `.turbo/plans/*.md`. If exactly one file exists, use it 4. **Most recent** — most recently modified file 5. **Legacy fallback** — `.turbo/plan.md` if `.turbo/plans/` does not exist 6. **Nothing found** — tell the user to run `/turbo:plan` and stop

If multiple candidates exist and the choice is non-obvious, use `AskUserQuestion`.

State the resolved path before continuing.

Unless an explicit path or slug was passed, confirm the resolved plan still describes work that remains to be done. The signal is a frontmatter `status:` of `done`.

When the signal fires, output it as text. Then use `AskUserQuestion` to offer:

• **Refine anyway** — the marker is stale
• **Pick another plan** — resolve to a different file under `.turbo/plans/`, then confirm that plan against this same signal
• **Leave the plan alone** — skip refining

On **Leave the plan alone**, mark the remaining refine steps deleted, then use the TaskList tool and proceed to any remaining task.

Once the plan is settled, resolve the ledger as Loop State describes.

Loop State

Loop state lives in a ledger at `.turbo/loops/refine-plan-<label>-<tag>.md`. The label is the resolved plan's slug, or the file's basename for a legacy single-file fallback. 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:` (the resolved plan path), a one-line purpose, and per iteration an `Iteration <N>: <state>` line, its verdicts, and Step 5's classification. A ledger that exists belongs to an active loop.

Resolve the ledger:

• **Carried path:** this invocation was passed a ledger path, by the re-run Step 5 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 ledgers in `.turbo/loops/` that git does not track whose name starts with `refine-plan-` and whose `Plan:` is the resolved plan, on any branch. Output each one's purpose, last iteration and its state, and file modification time as text. 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. Discarding deletes the named ledger, then discovery runs again.
• **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 5 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 5 reaches a gate, `awaiting <gate>` while Step 5 waits on the user at one (the prose-only round, the skip permission, the hard cap, the context-signal question recorded with the gate it wraps, or a hands-on check), and `classified` once Step 5 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 2-4, so mark this invocation's Step 2-4 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 left the plan unchanged, the loop has ended, so delete the ledger. For `awaiting hands-on check`, ask for the check's result, or read the log the ledger names. Then proceed by the answer as Step 5 does.
• `open`: the iteration was interrupted. Rerun it under its own number from Step 2. The verdicts it already recorded stand: Step 3 keeps them rather than recording them again.

A compaction in flight is not a resume: this invocation continues its own iteration.

**Recording.** Have the ledger path in context when Steps 2 and 3 run, so recorded verdicts are honored. Append each Skip, Escalate, and Apply verdict with its reason under the current iteration as Steps 3-4 reach it, along with the user's resolution of an Escalate.

**Closing the loop.** Delete the ledger at a convergence stop, at a stop the user chooses at a gate, and at a stop granted at the skip gate. Keep it when escalating to `/consult-oracle`, since the oracle's answer decides what follows.

Step 2: Run `/review-plan` Skill

Run the `/review-plan` skill on the resolved plan. Supply every Skip and