refine-plan

name	refine-plan
disable-model-invocation	false
argument-hint	<plan-file> [rounds N] [auto] [<guidance>]
description	Refine an in-progress plan by reviewing remaining phases against completed work. Dispatches reviewer + devil's-advocate agents to surface stale references, invalidated assumptions, and specification gaps, then refines until convergence. Completed phases are NEVER modified. Appends a Drift Log + Plan Review.
metadata	{"version":"2026.06.03+be05a3"}

/refine-plan <plan-file> [rounds N] [] — Adversarial Plan Refiner

Refines an existing plan that is partially executed. Completed phases represent real, shipped work — they are immutable context, never modification targets. The refiner reviews only the remaining phases against what was actually built (not what was planned), then iteratively improves them through adversarial review cycles.

The insight: plans drift during execution. Completed phases may have built something different from what was originally specified. Remaining phases still reference the original spec. /refine-plan closes this gap by reviewing remaining phases against the actual state of completed work, not the planned state.

Completed phases are NEVER modified. They are read-only context that informs the review. Not even heading typo fixes. Immutability is verified mechanically: completed phase sections must be byte-identical before and after refinement.

Ultrathink throughout.

Preflight — top-level dispatch required

This skill internally dispatches reviewer + devil's-advocate + refiner sub-agents in parallel. It MUST run in a context that has the Agent (or Task) tool available.

Before doing any other work, verify your tool list contains Agent or Task. If neither is present, STOP and report:

ERROR: /refine-plan requires top-level Agent dispatch capability. This invocation is running as a subagent (no Agent tool — verified by inspecting your tool list). Subagents cannot dispatch sub-subagents (Anthropic design — https://code.claude.com/docs/en/sub-agents).

Re-invoke as one of:

• User slash command: /refine-plan <plan-file>
• Top-level Skill tool: Skill(skill="refine-plan", args="<plan-file>")
• Inline orchestration by a top-level Claude that has Agent

Do NOT continue. Single-agent inline degradation produces rubber-stamp findings without the adversarial diversity this skill's value depends on. The CLAUDE.md memory anchor feedback_multi_agent_skills_top_level.md is the recurring failure mode this preflight catches.

Do not proceed past this preflight without Agent access.

Worktree preamble — ensure isolation when main is protected

Before parsing arguments, ensure a worktree exists when main is protected. Dispatch the canonical helper; if main_protected: true and the caller is in main, the helper creates a worktree and prints its path on stdout (empty string when no worktree is required). When non-empty, cd into it and export ZSKILLS_PATHS_ROOT so downstream path-resolution anchors on the worktree, not main:

MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
TOPLEVEL=$(git rev-parse --show-toplevel)
HELPER="$ZSKILLS_SKILLS_ROOT/create-worktree/scripts/ensure-worktree.sh"
# Caller-side install-integrity fallback (DA-R3-2): if /update-zskills
# Step 3 ran as per-file-diff and skipped the new file, the helper itself
# is missing. Emit an actionable exit-11 message instead of bash's
# `No such file or directory`.
if [ ! -x "$HELPER" ]; then
  echo "refine-plan: ensure-worktree.sh missing at $HELPER — run /update-zskills to repair" >&2
  exit 11
fi
# Resolve $PLAN_FILE and derive $TRACKING_ID before the worktree preamble
# so the helper's --pipeline-id / positional slug are non-empty. Mirrors
# the Arguments-section detection rule: first $ARGUMENTS token ending in
# `.md` is the plan file; resolve bare names via $ZSKILLS_PLANS_DIR.
# Phase 1's Tracking-fulfillment fence re-uses $TRACKING_ID idempotently.
if [ -z "${PLAN_FILE:-}" ]; then
  if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-paths.sh" ]; then
    export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
    . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-paths.sh"
  else
    . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-paths.sh"
  fi
  for tok in $ARGUMENTS; do
    case "$tok" in
      */*) PLAN_FILE="$tok"; break ;;
      *.md) PLAN_FILE="$ZSKILLS_PLANS_DIR/$tok"; break ;;
    esac
  done
fi
if [ -z "${PLAN_FILE:-}" ]; then
  echo "refine-plan: PLAN_FILE not resolved from \$ARGUMENTS (need a *.md token)" >&2
  exit 2
fi
TRACKING_ID=$(basename "$PLAN_FILE" .md | tr '[:upper:]' '[:lower:]' | tr '_' '-')
WT_PATH=$(bash "$HELPER" \
  --prefix refineplan \
  --pipeline-id "refine-plan.${TRACKING_ID}" \
  --allow-resume \
  --purpose "refine-plan auto-worktree; isolate plan refinement from main" \
  "${TRACKING_ID}")
RC=$?
if [ "$RC" -ne 0 ]; then
  echo "ensure-worktree failed (rc=$RC) for /refine-plan" >&2
  # rc=3 (poisoned branch): suggest `/create-worktree resume <slug>` or
  # delete the poisoned branch. rc=11: helper install-integrity — run
  # `/update-zskills` to repair. Other codes: see helper script header.
  exit "$RC"
fi
if [ -n "$WT_PATH" ]; then
  cd "$WT_PATH" || { echo "refine-plan: cd $WT_PATH failed" >&2; exit 1; }
  # R3-1 path-resolution fix: re-anchor zskills-paths.sh under the
  # worktree so subsequent $ZSKILLS_PLANS_DIR / $ZSKILLS_AUDIT_DIR /
  # $ZSKILLS_ISSUES_DIR resolutions land in WT, not main. Export (not
  # just set) so child shells / re-sourcing inherits it.
  export ZSKILLS_PATHS_ROOT="$WT_PATH"
fi
# Empty $WT_PATH means no worktree was created (caller already in one OR
# main not protected); proceed in cwd. $ZSKILLS_PATHS_ROOT stays unset
# in that case, so paths fall back to $CLAUDE_PROJECT_DIR as before.

Arguments

/refine-plan <plan-file> [rounds N] [auto] [guidance...]

• plan-file (required) — path to the plan .md file to refine.
• rounds N (optional) — max review/refine cycles. Default: 2. The process exits early if a round converges (no substantive new issues). Default is 2 (not 3 like /draft-plan) because this is a refinement pass on an existing plan, not blank-slate creation.
• auto (optional positional token) — after the worktree auto-commit in Phase 5 succeeds, dispatch /land-pr to push the branch, open a PR, monitor CI, and auto-merge. Without auto, the refined plan is committed in the worktree but no PR is opened. Mirrors auto in /run-plan, /do, /fix-issues, /quickfix, /draft-plan.

Detection: scan $ARGUMENTS from the start:

• The first token ending in .md is the plan file. If the token contains /, use as-is; otherwise resolve via $ZSKILLS_PLANS_DIR/<token> (sourcing .claude/skills/update-zskills/scripts/zskills-paths.sh from the orchestrator's bash fence; falls back to plans/ when config silent).
• rounds followed by a numeric argument sets max cycles. (rounds not followed by a number is treated as guidance text, not the keyword.)
• auto (whitespace-anchored, case-insensitive) sets AUTO_FLAG=1 for the Phase 5 /land-pr dispatch. The token is consumed by the flag parse and does NOT enter guidance text.
• Any tokens not matched as the plan file or rounds N keyword OR the auto token are joined with spaces into guidance text — prepended to the reviewer + devil's advocate agent prompts in Phase 2 as a "User-driven scope/focus directive" section.
• Empty guidance preserves today's reviewer/DA prompt output (no behavior change for invocations without trailing guidance tokens).
• If no plan file is detected, error: "No plan file specified. Usage: /refine-plan <plan-file> [rounds N] [auto] [guidance...]"

Argument parser

The single source of truth for argument parsing. One extractable fence implements the Detection rules above verbatim — plan-file resolution ($ZSKILLS_PLANS_DIR must already be sourced, as in the worktree preamble), rounds N, the auto flag, and guidance-tail joining. The worktree preamble re-derives $PLAN_FILE independently (it runs before this fence to seed the helper's pipeline-id); this fence is the canonical parse the rest of the skill reads (ROUNDS_MAX, AUTO_FLAG, GUIDANCE).

# Inputs: $ARGUMENTS (raw), $ZSKILLS_PLANS_DIR (resolved by the preamble).
# Outputs: PLAN_FILE, ROUNDS_MAX (default 2), AUTO_FLAG (0/1), GUIDANCE.

# auto — whitespace-anchored, case-insensitive (consumed; not guidance).
AUTO_FLAG=0
if [[ "$ARGUMENTS" =~ (^|[[:space:]])[aA][uU][tT][oO]($|[[:space:]]) ]]; then
  AUTO_FLAG=1
fi

# plan-file — first token with a `/` (use as-is) else first `*.md`
# (resolve via $ZSKILLS_PLANS_DIR). Mirrors the worktree-preamble loop.
if [ -z "${PLAN_FILE:-}" ]; then
  for tok in $ARGUMENTS; do
    case "$tok" in
      */*) PLAN_FILE="$tok"; break ;;
      *.md) PLAN_FILE="$ZSKILLS_PLANS_DIR/$tok"; break ;;
    esac
  done
fi

# rounds N + guidance tail. Single pass: `rounds` followed by a numeric
# token sets ROUNDS_MAX (both consumed); `rounds` NOT followed by a number
# is plain guidance. The plan-file token and the `auto` token are consumed
# (never guidance). Everything else joins GUIDANCE in order. Default
# ROUNDS_MAX=2.
ROUNDS_MAX=2
GUIDANCE=""
prev_rounds=0
for tok in $ARGUMENTS; do
  # Resolve a pending `rounds` against the current token.
  if [ "$prev_rounds" -eq 1 ]; then
    prev_rounds=0
    case "$tok" in
      ''|*[!0-9]*) GUIDANCE="${GUIDANCE:+$GUIDANCE }rounds" ;;  # not a number
      *)           ROUNDS_MAX="$tok"; continue ;;               # rounds N consumed
    esac
  fi
  # Skip the consumed plan-file token.
  if [ -n "${PLAN_FILE:-}" ]; then
    case "$tok" in
      */*)  [ "$tok" = "$PLAN_FILE" ] && continue ;;
      *.md) [ "$ZSKILLS_PLANS_DIR/$tok" = "$PLAN_FILE" ] && continue ;;
    esac
  fi
  case "$tok" in
    rounds)              prev_rounds=1; continue ;;  # decided next iteration
    [aA][uU][tT][oO])    continue ;;                 # auto consumed
    *) GUIDANCE="${GUIDANCE:+$GUIDANCE }$tok" ;;
  esac
done
# A trailing `rounds` with no following token is guidance.
[ "$prev_rounds" -eq 1 ] && GUIDANCE="${GUIDANCE:+$GUIDANCE }rounds"

Examples:

• /refine-plan plans/EXECUTION_MODES.md
• /refine-plan plans/EXECUTION_MODES.md rounds 3
• /refine-plan THERMAL_PLAN.md -> reads $ZSKILLS_PLANS_DIR/THERMAL_PLAN.md
• /refine-plan rounds 2 plans/FEATURE.md -> plan file is plans/FEATURE.md, 2 rounds
• /refine-plan plans/FOO.md anti-deferral focus
• /refine-plan plans/FOO.md rounds 3 expand audit to all config fields

Phase 1 — Parse Plan

Tracking fulfillment

Determine the tracking ID: use the ID passed by the parent skill if this is a delegated invocation, or derive from the plan file slug if standalone (e.g., plans/EXECUTION_MODES.md -> execution-modes). Create the fulfillment file in the MAIN repo. The pipeline subdir follows Option B layout: when delegated, parent exports ZSKILLS_PIPELINE_ID via env and we write into the parent's subdir; when standalone, we own our own subdir:

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
PIPELINE_ID="${ZSKILLS_PIPELINE_ID:-refine-plan.$TRACKING_ID}"
PIPELINE_ID=$(bash "$ZSKILLS_SKILLS_ROOT/create-worktree/scripts/sanitize-pipeline-id.sh" "$PIPELINE_ID")
[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
mkdir -p "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID"
printf 'skill: refine-plan\nid: %s\nplan: %s\nstatus: started\ndate: %s\n' \
  "$TRACKING_ID" "$PLAN_FILE" "$(TZ="${TIMEZONE:-UTC}" date -Iseconds)" \
  > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/fulfilled.refine-plan.$TRACKING_ID"

Parse the plan file

1. Read the plan file. If it does not exist, error: "Plan file <path> not found."

2. Parse YAML frontmatter — extract title, status, issue, etc.

3. Parse the Progress Tracker table. For each phase row, classify:

   • Completed: Status column contains Done, a checkmark (✅), or [x] (case-insensitive).
   • Remaining: everything else — ⬚, In Progress, Blocked, empty, or any other value.
   • Sub-phases (e.g., 3a, 3b) are classified independently.

4. Extract phase sections. For each phase heading (## Phase N — Name), extract the full section text. Associate each section with its completed/remaining classification from the Progress Tracker.

5. Validate:

   • At least one remaining phase must exist. If all phases are completed, exit cleanly: "All phases complete — nothing to refine. Run with a plan that has remaining phases."
   • If no Progress Tracker table is found, attempt to infer phase status from section content (e.g., presence of commit hashes, [x] in work items). If unable to infer, error: "No Progress Tracker found in <path>. Add a Progress Tracker table with phase status columns so the refiner can distinguish completed from remaining phases."

6. Compute checksums of each completed phase section (the full text from ## Phase N to the next ## Phase or end of file). These checksums are used in Phase 5 to verify byte-identical immutability.

7. Write parsed state to /tmp/refine-plan-parsed-<slug>.md where <slug> comes from the plan filename (e.g., EXECUTION_MODES from plans/EXECUTION_MODES.md). Include:

   • List of completed phases with checksums
   • List of remaining phases with full text
   • YAML frontmatter values
   • Plan file path

   This file persists across context compaction. All subsequent phases read from it if context is lost.

Phase 2 — Adversarial Review (parallel agents)

Dispatch two agents simultaneously. Both receive:

• The full plan text
• Completed phases clearly marked as READ-ONLY CONTEXT (not review targets)
• Remaining phases as the REVIEW TARGET
• The parsed state file path (/tmp/refine-plan-parsed-<slug>.md)

If guidance was supplied (positional-tail tokens after the plan file and rounds N, joined with spaces): prepend a User-driven scope/focus directive: section to BOTH the reviewer and devil's advocate agent prompts, containing the guidance text verbatim. Agents treat this as priming context that shapes WHAT they pressure-test — NOT as factual claims they should act on without verification (verify-before-fix discipline still applies). If guidance is empty, the agent prompts are unchanged from today's output.

Establishing current reality (preamble — both agents)

Before applying any of the six review dimensions, both agents must establish current reality. The dimensions ask whether remaining phases' references, assumptions, and acceptance criteria hold — that question has no meaningful answer without knowing what reality now looks like.

1. Read the codebase state for anything remaining phases will interact with — source files, skills, configs, docs, schemas, whatever. The plan text may be stale; reality is what exists.

2. Check what completed phases actually produced (via commit diffs or current file state) vs what they planned. Where they diverged, reality wins; note the divergence in the Drift Log but do NOT modify the completed phase section.

3. Incorporate changes outside the plan — recent external commits, known fixes, user-provided context. Reality includes everything, not just phase output.

4. Treat remaining phases as a coherent whole. Even if the plan was recently patched in only some sections, review how any changes ripple forward into all other remaining phases. Do not focus review only on recently-edited sections — the plan's cohesion comes from how ALL remaining phases fit together.

5. Dry-run each remaining phase against current reality. For each remaining phase, step through what it will do at execution time. Where does it invoke skills, touch files, query configs, or make API calls? At every external interaction point, check what current reality will produce:

   • Skill invocation → read the skill's current text and simulate each stage of its flow. At each stage, ask: does this stage's behavior still make sense given the mode/options the phase will invoke the skill in, and given anything completed phases added to the skill? Pay special attention to pre-existing stages that weren't touched by completed phases but will now run alongside new ones.
   • File write → check whether the file exists, what convention surrounds it, whether the write respects that convention.
   • Config query → check the config's current value, not the value the plan assumes.
   • API/tool call → check the current signature and behavior.

   Flag any step where reality produces different behavior than the remaining phase expects. This catches mode-conditional drift (rules written for an old default that silently misbehave under a new mode added by completed phases) that dimensions 1-6 can miss when applied only against plan text.

Only then apply dimensions 1-6 against that reality.

Reviewer agent

Reviews remaining phases against the reality of completed work. Checks these six dimensions:

1. Stale references — code, files, APIs, data structures, or paths mentioned in remaining phases that were replaced, renamed, or removed by any source (completed phases, external changes, or recent patches). The plan may reference src/old-module.js but reality moved it to src/new-module.ts.

2. Consistency — do remaining phase specs match current reality (the codebase, completed phases' actual output, recent changes) — not what the plan originally planned? Where completed phases deviated from their spec, or external changes shifted things, the code is reality.

3. Sizing — are remaining phases still right-sized (~3-5 components, ~500 lines) given what's known now? Completed work may have changed the scope of what remains.

4. Specification gaps — do remaining phases reference decisions, APIs, or data structures that are missing from reality or inconsistent with it? The gap may be in what completed phases were supposed to define but didn't, in what external changes introduced that the plan doesn't account for, or in remaining phases that reference a convention/rule elsewhere in the codebase that has since changed.

5. Dependency correctness — are remaining phase dependencies correct given completed work and remaining phase ordering? A dependency on Phase 2 may be satisfied if Phase 2 is done, or may need updating if Phase 2 built something different.

6. Acceptance criteria coverage — do acceptance criteria in remaining phases cover all work items? Are criteria still valid given what completed phases actually produced?

7. Numeric target arithmetic — for every numeric acceptance target (line counts, file counts, heading counts, commit counts, test counts, extracted-range sizes), re-derive the expected value arithmetically from the plan's stated extraction rules and current source state, then compare against the plan's acceptance band. Flag any drift >10% as a stale numeric target. This is the dimension that catches plan-authoring arithmetic errors — e.g., "SKILL.md line count 340-380 after extraction" when the math gives 278, or "expected ~620 lines" when the range is actually 661. Always flag even if the intent is clear — a stale numeric band in an acceptance criterion forces the implementing agent to either reject correct work or log "non-blocking plan-text issue" (both of which are failure modes). Example verification: echo "417 - 94 - 60 + 15 = $((417-94-60+15))" — produce the exact arithmetic as your Verification line.

Each finding must be specific and actionable: cite the exact section, line, or reference that's wrong and what it should say instead.

Evidence discipline. When a finding makes an empirical claim (a file has/lacks X, a function does Y, a tool's input contains Z), include a concrete Verification: line — the exact file:line, grep, schema quote, or command output that reproduces the evidence. The refiner will re-run these checks before acting. Structural/judgment findings ("this phase mixes too many concerns") don't need a reproducer, but mark them explicitly: Verification: judgment — no verifiable anchor. Never write an empirical-sounding claim without something the refiner can independently re-check.

Devil's Advocate agent

Genuinely adversarial — tries to find ways the remaining plan will fail given what's already been built. Checks these six dimensions:

1. Invalidated assumptions — assumptions in remaining phases that completed work disproved. "Phase 4 assumes the solver returns a flat array, but Phase 2 actually returns a typed object."

2. Unnecessary work items — things remaining phases plan to do that completed phases already handled. Duplicate work wastes agent time and risks conflicts.

3. Deferred hard parts — difficult items hidden behind vague language in remaining phases. "Phase 5: integrate everything" — that's where all the complexity actually lives.

4. Hidden dependencies — undeclared dependencies between remaining phases. Phase 4 may silently need output from Phase 3 without listing it as a dependency.

5. Scope drift — remaining phases that grew beyond original intent without justification. Compare against the plan's Overview section.

6. Integration risks — ways remaining work will break when combined with completed work. What interfaces exist between completed and remaining phases? Are they compatible?

7. Numeric target arithmetic (adversarial) — same as reviewer dimension 7, but from an adversarial stance: find numeric targets the plan states that are unreachable given the plan's own extraction rules. Past failure (RESTRUCTURE_RUN_PLAN, 2026-04-19): three phases shipped with acceptance bands arithmetically unreachable (Phase 1 340-380 vs actual 277; Phase 3 850-950 vs 1057; Phase 4 700-900 vs 1534). Each was caught post-hoc by implementation agents who flagged "plan-text issue, non-blocking." All three would have been caught by arithmetic verification at refine-plan time. Do the math. If the plan's "remove 154 lines, add 15, expect 357" doesn't balance, say so. Example verification: python3 -c "print(417-94-60+15)" or equivalent bash.

Each finding must be specific and actionable — not generic concerns. "Phase 3 might be complex" is useless. "Phase 3 says 'implement the export pipeline' but doesn't specify the serialization format, and Phase 1 already committed to MessagePack in src/io.ts — the agent will have to guess or conflict" is actionable.

The same evidence discipline from the reviewer section applies: every empirical claim needs a Verification: line (file:line, grep, schema quote, etc.). The devil's advocate is especially prone to generating plausible-sounding-but-false claims because its job is pattern-generating failure modes, not verifying them. Discipline is load-bearing here.

Write findings

Write combined findings to /tmp/refine-plan-review-round-N-<slug>.md (e.g., /tmp/refine-plan-review-round-1-EXECUTION_MODES.md). Include reviewer findings and devil's advocate findings in separate sections. If the file already exists from a prior invocation, overwrite (not append).

Post-review tracking

After both agents return, create the review step marker:

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
PIPELINE_ID="${ZSKILLS_PIPELINE_ID:-refine-plan.$TRACKING_ID}"
PIPELINE_ID=$(bash "$ZSKILLS_SKILLS_ROOT/create-worktree/scripts/sanitize-pipeline-id.sh" "$PIPELINE_ID")
[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
printf 'round: %s\ncompleted: %s\n' "$ROUND" "$(TZ="${TIMEZONE:-UTC}" date -Iseconds)" \
  > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/step.refine-plan.$TRACKING_ID.review"

Phase 3 — Refine

A single agent receives:

• The current remaining phases text
• All findings from Phase 2 (from the /tmp/ findings file)
• Completed phases as READ-ONLY CONTEXT (for reference only)
• The parsed state file path

Verify-before-fix (mandatory)

Before touching any phase text, the refiner must attempt to reproduce the cited evidence for each finding. The reviewer/DA produce hypotheses; the refiner is the gate that tests them against reality. This is not optional.

For each finding with an empirical claim:

1. Read the Verification: line and run its check (Read the file, run the grep, check the schema, run the command).
2. Record one of three outcomes in the disposition table:
   • Verified — evidence reproduces. Proceed with fix or justification.
   • Not reproduced — the cited evidence does not match reality. Disposition: Justified — evidence did not reproduce. Note what was actually found. Do NOT fix based on this finding.
   • No anchor — finding is empirical-sounding but lacks a verifiable citation. Disposition: Justified — claim not verifiable as stated unless the refiner can locate a verifiable anchor itself.

Judgment findings (those explicitly marked Verification: judgment) skip step 1 and go straight to fix-or-justify based on merit.

Why this exists. Past failure: a devil's advocate claimed a Claude Code tool's input JSON lacked a model field and cited the hook template as evidence. The hook template was real but irrelevant — the actual falsifier was the tool's own schema, which did contain the field. The refiner accepted the claim and pivoted a whole phase's architecture based on nothing. If the refiner had tried to reproduce the evidence, it would have discovered the claim was unsupported. Verify-before-fix turns "I believe the DA" into "I checked."

Address every finding

The agent addresses every finding. For each finding, it must either:

1. Fix it — update the remaining phase text to resolve the issue
2. Justify — explain with evidence why it's not actually a problem (including the "evidence did not reproduce" and "claim not verifiable" cases from the verify-before-fix block)

It may NOT ignore findings or defer them. Every finding gets a disposition.

The disposition table (written to the refined output) must include an Evidence column with the outcome: Verified, Not reproduced, No anchor, or Judgment (for non-empirical findings).

Completed phases are NEVER modified. The refiner operates only on remaining phase text. If a finding suggests a completed phase has a problem, the refiner notes it in the Plan Review section as a known issue — it does not touch the completed phase.

Output is the updated remaining phases only. Write the refined text to /tmp/refine-plan-refined-round-N-<slug>.md for persistence.

Phase 4 — Convergence Check

Convergence is the orchestrator's judgment, not the refiner's self-call. Do NOT accept "CONVERGED" from the refiner agent as authoritative — the refiner just refined; it is biased toward declaring its own work done. This is a recurring failure mode in practice.

After each round of review + refinement:

1. Count remaining substantive issues from the refiner's disposition table (Justified-not-fixed entries plus any gaps the refinement introduced).

2. Check convergence:

   • 0 substantive issues -> converged -> next phase.
   • >0 substantive issues AND rounds < max -> another review+refine cycle, back to Phase 2 with the refined draft as the new input. Honor the user's rounds budget; don't stop early.
   • Only short-circuit before max rounds when remaining substantive issues are genuinely 0.

3. Track round history — record each round's finding counts and resolutions. This goes into the Plan Review section in Phase 5.

Phase 5 — Write Updated Plan

Reassemble the plan file by concatenating in order:

1. Original YAML frontmatter (unchanged, byte-for-byte)
2. Original title + Overview section (unchanged, byte-for-byte)
3. Progress Tracker table (unchanged, byte-for-byte)
4. Completed phases (unchanged, byte-for-byte — verified by comparing checksums from Phase 1 against the sections about to be written. If any checksum differs, STOP and report the mismatch. Do not write a file with modified completed phases.)
5. Refined remaining phases (from the last refinement round)

Write the reassembled plan in place to the original plan file path. Do NOT write to a new path.

Drift Log

Append a ## Drift Log section after the last phase. This documents where completed phases diverged from the plan-as-originally-written. It is a historical record for future readers — it does NOT modify completed phases.

To identify drift:

1. Run git log --follow --stat <plan-file> to find all commits that touched the plan (summary only, avoids context overflow). Use --all to search across all refs, including worktree branches where the original version may only exist.

2. Run git show <earliest-reachable-commit>:<plan-file> to retrieve the original version of the plan.

3. Compare structurally — not raw diffs. Compare:

   • Phase headings (added, removed, renamed)
   • Phase count (original vs current)
   • Work item counts per phase (original vs current)
   • Any phases that were split or merged

4. If only one commit exists for the file (no prior version), note: "No prior version available — drift log based on current state only."

5. Graceful fallback: if git log or git show fails (e.g., plan was created outside git, or the repo has no history), note the failure and produce a drift log based on internal evidence only (e.g., completed phases whose work items don't match their acceptance criteria).

Format as a table:

## Drift Log

Structural comparison of the plan as originally drafted vs current state.

| Phase | Planned | Actual | Delta |
|-------|---------|--------|-------|
| 1 — Setup | 4 work items | 6 work items | +2 items (auth added during impl) |
| 2 — Core | 3 components | 3 components | No drift |
| 3 — UI | "Dark mode toggle" | "Theme system" | Scope expanded |

Plan Review

Append a ## Plan Review section after the Drift Log. Document:

## Plan Review

**Refinement process:** /refine-plan with N rounds of adversarial review
**Convergence:** [Converged at round M / Max rounds reached]
**Remaining concerns:** [None / List of unresolved issues]

### Round History
| Round | Reviewer Findings | Devil's Advocate Findings | Substantive | Resolved |
|-------|-------------------|---------------------------|-------------|----------|
| 1     | 5 issues          | 4 issues                  | 7           | 7/7      |
| 2     | 1 issue           | 0 issues                  | 0           | Converged|

Auto-commit the plan file (if in a worktree)

After appending the Plan Review section, when $TOPLEVEL is a worktree (not main), stage and commit $PLAN_FILE so the refined plan is captured on the feature branch rather than left dirty in main. This pairs with the preamble's structural isolation:

# Self-contained; belt-and-suspenders cd in case WT_PATH was set above.
[ -n "${WT_PATH:-}" ] && cd "$WT_PATH" 2>/dev/null || true
MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
TOPLEVEL=$(git rev-parse --show-toplevel)
if [ "$TOPLEVEL" != "$MAIN_ROOT" ]; then
  # Re-source path-config under the worktree root so $ZSKILLS_PLANS_DIR
  # etc resolve to TOPLEVEL/... rather than $CLAUDE_PROJECT_DIR/... — R3-1.
  # Belt-and-suspenders: the preamble already exported this, but the
  # fence re-exports in case the preamble code path was bypassed
  # (e.g., caller-in-worktree, where WT_PATH was empty but TOPLEVEL is
  # already a worktree — we want paths anchored on TOPLEVEL).
  export ZSKILLS_PATHS_ROOT="$TOPLEVEL"
  if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-paths.sh" ]; then
    export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
    . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-paths.sh"
  else
    . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-paths.sh"
  fi

  # R3-1 path-remap: if $PLAN_FILE was computed BEFORE the preamble set
  # $ZSKILLS_PATHS_ROOT (e.g., a stale value cached in the caller's
  # argument-resolution block), it may still be MAIN-anchored. Re-anchor
  # to TOPLEVEL. This is the load-bearing remap.
  case "$PLAN_FILE" in
    "$MAIN_ROOT"/*) PLAN_FILE="$TOPLEVEL/${PLAN_FILE#"$MAIN_ROOT/"}" ;;
  esac

  # Portable FILE_REL (DA-R2-1, R3-6: adapted from warn-config-drift.sh:181-203).
  FILE_REL=""
  if FILE_REL=$(realpath --relative-to="$TOPLEVEL" "$PLAN_FILE" 2>/dev/null) \
       && [ -n "$FILE_REL" ]; then
    case "$FILE_REL" in /*) FILE_REL="" ;; esac
  fi
  if [ -z "$FILE_REL" ]; then
    ABS_FILE=$(cd "$(dirname "$PLAN_FILE")" 2>/dev/null && pwd)/$(basename "$PLAN_FILE")
    case "$ABS_FILE" in
      "$TOPLEVEL"/*) FILE_REL="${ABS_FILE#"$TOPLEVEL"/}" ;;
      *) echo "refine-plan: cannot normalize $PLAN_FILE vs $TOPLEVEL" >&2; exit 1 ;;
    esac
  fi
  # Out-of-tree guard (DA-R2-5). After the path-remap above, FILE_REL
  # should never be `../*` for legitimate inputs; if it is, fail loud
  # (something is wrong with the caller's resolution).
  case "$FILE_REL" in
    /*|../*) echo "refine-plan: $PLAN_FILE is outside worktree $TOPLEVEL" >&2; exit 1 ;;
  esac

  git -C "$TOPLEVEL" add "$FILE_REL"
  STAGED=$(git -C "$TOPLEVEL" diff --cached --name-only)
  if [ "$STAGED" != "$FILE_REL" ]; then
    echo "refine-plan: unexpected staged set: $STAGED (expected $FILE_REL only)" >&2
    exit 1
  fi
  if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
    export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
    . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
  else
    . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
  fi

  # Per-skill commit subject (R2-F8: case-stmt, not table cell).
  BASE=$(basename "$FILE_REL" .md)
  case "refine-plan" in
    draft-plan)  COMMIT_MSG_SUBJECT="docs(plans): draft $BASE" ;;
    refine-plan) COMMIT_MSG_SUBJECT="docs(plans): refine $BASE" ;;
    draft-tests) COMMIT_MSG_SUBJECT="docs(tests): draft test specs for $BASE" ;;
  esac

  if [ -n "$COMMIT_CO_AUTHOR" ]; then
    git -C "$TOPLEVEL" commit --trailer "Co-Authored-By: $COMMIT_CO_AUTHOR" -m "$COMMIT_MSG_SUBJECT"
  else
    git -C "$TOPLEVEL" commit -m "$COMMIT_MSG_SUBJECT"
  fi
fi

Auto-land via /land-pr (when auto was passed)

Issue #581: in projects with execution.landing: pr + main_protected: true, the refined plan file is committed in the worktree (above) but never reaches main without a /land-pr dispatch. When the user passed the auto positional token, dispatch /land-pr so the branch pushes, a PR opens, CI runs, and auto-merge lands the refined plan on main. Without auto, the worktree commit stands and the caller lands manually.

if [ "${AUTO_FLAG:-0}" = "1" ] && [ "$TOPLEVEL" != "$MAIN_ROOT" ]; then
  if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
    export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
    . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
  else
    . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
  fi
  BRANCH_NAME=$(git -C "$TOPLEVEL" rev-parse --abbrev-ref HEAD)
  SLUG="$TRACKING_ID"
  PR_TITLE="docs(plans): refine $(basename "$PLAN_FILE" .md) via /refine-plan"
  BODY_FILE="/tmp/pr-body-refine-plan-${SLUG}-$$.md"
  RESULT_FILE="/tmp/land-pr-result-refine-plan-${SLUG}-$$.txt"
  cat > "$BODY_FILE" <<BODY
## Summary

\`/refine-plan\` updated \`$PLAN_FILE\` via $ROUND round(s) of adversarial
review (reviewer + devil's-advocate + refiner). Completed phases were
NOT modified (checksum-gated). Pending phases were refined; \`## Drift
Log\` and \`## Plan Review\` sections appended.

## Test plan

- [x] Refined plan committed on the refine-plan branch (worktree-isolated)
- [x] Completed-phase byte-identity verified via Phase-1 checksums
- [ ] No functional tests — this PR ships a plan document only; CI will
      run skill-conformance / hook / fixture suites
BODY
  LAND_ARGS="--branch=$BRANCH_NAME --title=\"$PR_TITLE\" --body-file=$BODY_FILE --result-file=$RESULT_FILE --landed-source=refine-plan --worktree-path=$TOPLEVEL --tracking-id=refine-plan.$SLUG --auto"

  # Skill: { skill: "land-pr", args: "$LAND_ARGS" }

  # Allow-list parse the /land-pr result (canonical caller-loop pattern —
  # never `source`). See skills/land-pr/references/caller-loop-pattern.md.
  if [ -f "$RESULT_FILE" ]; then
    declare -A LP
    while IFS='=' read -r KEY VALUE; do
      case "$KEY" in
        STATUS|PR_URL|PR_NUMBER|CI_STATUS|PR_STATE|REASON)
          LP["$KEY"]="$VALUE" ;;
        "") ;;
        *) ;;  # unknown keys ignored (forward-compat)
      esac
    done < "$RESULT_FILE"
    echo "/land-pr: STATUS=${LP[STATUS]:-?} CI_STATUS=${LP[CI_STATUS]:-?} PR=${LP[PR_URL]:-none}" >&2
    rm -f "$RESULT_FILE"
  else
    echo "WARN: /refine-plan: /land-pr produced no result file at $RESULT_FILE" >&2
  fi
fi

Post-write tracking

After writing the updated plan file, create the finalize step marker and update the fulfillment file to complete:

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
MAIN_ROOT=$(cd "$(git rev-parse --git-common-dir)/.." && pwd)
PIPELINE_ID="${ZSKILLS_PIPELINE_ID:-refine-plan.$TRACKING_ID}"
PIPELINE_ID=$(bash "$ZSKILLS_SKILLS_ROOT/create-worktree/scripts/sanitize-pipeline-id.sh" "$PIPELINE_ID")
[ -n "$PIPELINE_ID" ] || { echo "tracking: empty PIPELINE_ID — refusing flat write" >&2; exit 1; }
printf 'completed: %s\n' "$(TZ="${TIMEZONE:-UTC}" date -Iseconds)" \
  > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/step.refine-plan.$TRACKING_ID.finalize"

printf 'skill: refine-plan\nid: %s\nplan: %s\nstatus: complete\ndate: %s\n' \
  "$TRACKING_ID" "$PLAN_FILE" "$(TZ="${TIMEZONE:-UTC}" date -Iseconds)" \
  > "$MAIN_ROOT/.zskills/tracking/$PIPELINE_ID/fulfilled.refine-plan.$TRACKING_ID"

Present the result

Plan refined in N rounds (converged / max rounds reached). [Remaining concerns if any]

Updated in place: <plan-file> Drift Log and Plan Review appended.

Continue execution with: /run-plan <plan-file>

Key Rules

• NEVER modify completed phases. They are immutable context — shipped work that cannot be changed by a plan refiner. Immutability is verified mechanically via checksums. Not even heading typo fixes.
• NEVER rewrite from scratch. Only refine remaining phases. The plan's structure, frontmatter, overview, progress tracker, and completed phases are preserved byte-for-byte.
• Every finding must be addressed. The refiner cannot ignore or defer reviewer/devil's-advocate findings. Fix it or justify why it's not a problem — with evidence.
• Verify findings before baking fixes. Reviewer and DA findings are hypotheses, not mandates. The refiner must reproduce each empirical claim before acting on it. A plausible-sounding claim with no verifiable anchor — or one whose evidence doesn't reproduce — is not a mandate to fix. It's a signal to scrutinize harder. Devil's advocate findings are especially prone to confidently-false empirical claims because the role incentivizes plausibility, not truth.
• Convergence is the orchestrator's call based on the refiner's disposition table, not the refiner's self-declaration. Run all budgeted rounds unless issues drop to 0.
• Write parsed state AND findings to /tmp/ files. Context compaction will degrade in-memory state across multiple rounds. The /tmp/ files persist through all phases. Read them if context is lost.
• Plan file updated IN PLACE. Do not write to a new path. The original path is the canonical location.
• Ultrathink throughout. Every agent in the process should use careful, thorough reasoning. Read completed phases carefully to understand what was actually built.
• Ground in reality before reviewing. The six dimensions work only if grounded in what actually exists. Shallow review of plan text alone — without reading the codebase, completed phases' real output, or recent external changes — applies the dimensions to an incomplete mental model and misses defects. This is the class of failure /refine-plan exists to prevent. The Phase 2 "Establishing current reality" preamble is mandatory, not advisory.
• Default 2 rounds. Lighter than /draft-plan's 3 because this is a refinement pass on an existing plan, not blank-slate creation.

Edge Cases

• Plan with no remaining phases — all phases are completed. Exit cleanly: "All phases complete — nothing to refine. Run with a plan that has remaining phases."
• Plan with no completed phases — review all phases. This is effectively a lighter /draft-plan review pass (2 rounds default vs 3). Still generate a Drift Log showing "No completed phases — all phases reviewed as remaining."
• Plan file doesn't exist — error: "Plan file <path> not found."
• Plan file has no Progress Tracker — attempt to infer status from phase section content (e.g., [x] checkboxes in work items, commit hashes in notes). If unable to infer, error: "No Progress Tracker found in <path>. Add a Progress Tracker table with phase status columns so the refiner can distinguish completed from remaining phases."
• Plan mid-execution by another agent — warn: "This plan may be actively executing. Refinement is advisory — changes will be written to the plan file but will not affect in-flight phase execution." Proceed with the review.
• Plan has sub-phases (3a/3b) — treat each sub-phase independently for completed/remaining classification. Sub-phase 3a can be completed while 3b is remaining.
• Round findings file already exists from prior invocation — overwrite, not append. Each invocation produces fresh findings.