plan-refine

name	plan-refine
description	Run a bounded iterative refinement loop over existing Prime Directive planning artifacts (`prd`, `tdd`, and `tasks-plan`) using one fresh reviewer subagent per critique round. Use when the user asks to improve, pressure-test, critique, iterate, loop on, or first-principles-review a plan before execution; supports `plan-key=KEY`, `--max-rounds=N`, and `--preserve-refine-artifacts`.

Plan Refine Skill

Run planning refinement only. Do not write implementation code.

Activation

Invoke explicitly with $plan-refine.

Activation examples:

• $plan-refine
• $plan-refine --max-rounds=8
• $plan-refine --preserve-refine-artifacts plan-key=<plan-key>

Required planning artifact set:

• tasks/prd-<plan-key>.md
• tasks/tdd-<plan-key>.md
• tasks/tasks-plan-<plan-key>.md

Supported modifiers:

• plan-key=<plan-key> when more than one complete planning set exists
• --max-rounds=<n>
• --preserve-refine-artifacts

Defaults:

• --max-rounds=8

Round limit:

• 8 is the hard maximum round count.
• If the user requests more than 8 rounds, cap the run at 8 rounds and mention the cap in the final response.

Fixed stop rule:

• Stop when a fresh reviewer round finds no blocker or material issues.
• Challenger objections alone do not trigger another round; only reviewer-classified blocker or material findings affect the stop rule.

Required References

Load these files before running:

• skills/shared/references/execution/task-file-contract.md
• skills/shared/references/planning/improve-plan.md
• skills/first-principles-mode/SKILL.md
• skills/first-principles-mode/references/analysis-rubric.md
• skills/shared/references/review/finding-disposition.md
• skills/shared/references/reasoning-budget.md

Workflow

1. Resolve the planning artifact set from plan-key=<plan-key> or the inference rules in task-file-contract.md.
   • If exactly one complete PRD/TDD/tasks-plan set exists under tasks/, bare $plan-refine must infer that plan-key and continue.
   • If multiple complete planning sets exist, stop and ask for plan-key=<plan-key>.
2. Stop immediately if any required artifact is missing. Tell the user the legacy PRD/TDD/tasks-plan set is incomplete, and suggest $deliver for new readable execution plans.
3. If deep research was used for the plan, load the research context before reviewer rounds.
   • Treat the plan as deep-research-backed when tasks/tmp/research-plan-<plan-key>.md exists or the TDD contains a durable research digest, Deep Research Completion Stamp, or evidence_bar_met value.
   • Prefer tasks/tmp/research-plan-<plan-key>.md when it still exists.
   • Otherwise read the durable research digest from tasks/tdd-<plan-key>.md.
   • Stop immediately if the research memo or TDD digest says evidence_bar_met: no; do not refine around a failed research evidence bar.
   • If deep research was used but neither the research memo nor a durable TDD digest is available, stop and report the missing research evidence instead of guessing.
4. If Pro analysis was used for the plan, load the Pro synthesis context before reviewer rounds.
   • Treat the plan as Pro-backed when tasks/tmp/pro-analysis-<plan-key>.md exists or the TDD contains a durable Pro synthesis digest or pro_synthesis_complete value.
   • Prefer tasks/tmp/pro-analysis-<plan-key>.md when it still exists.
   • Otherwise read the durable Pro synthesis digest from tasks/tdd-<plan-key>.md.
   • Stop immediately if the Pro synthesis memo or TDD digest is missing pro_browser_run: yes, pro_model_selected: yes, or pro_synthesis_complete: yes; do not refine around a failed, degraded, or missing Pro synthesis gate.
   • If Pro analysis was used but neither the Pro synthesis memo nor a durable TDD digest is available, stop and report the missing Pro synthesis evidence instead of guessing.
5. Stay on the current branch. Do not create, switch, rename, commit, or push branches.
6. Inspect git status --short.
   • Continue when the working tree is clean.
   • Continue when only the current plan artifacts are dirty.
   • If unrelated dirty files exist, report that they are unrelated and ignore them unless they prevent reading or editing the planning artifacts.
7. Create a temporary refinement log at tasks/tmp/plan-refine-<plan-key>.md.
8. Treat invocation of $plan-refine as an explicit request to delegate applicable challenger rounds and every critique round to fresh subagents.
   • The challenger lane is internal to $plan-refine; it does not add or change public invocation syntax or supported modifiers.
   • Spawn one fresh read-only challenger subagent only for applicable rounds: round == 1 OR previous_reviewer_round_had_blocker_or_material.
   • Spawn one fresh read-only reviewer subagent per round.
   • Request the strongest appropriate reasoning tier for each challenger and reviewer round, following reasoning-budget.md.
   • The challenger subagent must not edit files.
   • The reviewer subagent must not edit files.
   • The main agent owns orchestration, artifact edits, audit checks, refinement-log updates, and final user summary.
   • If a required fresh challenger or reviewer subagent cannot be spawned, stop immediately and tell the user this workflow requires subagents.
9. Before starting reviewer rounds, set the effective max round count.
   • Use the requested --max-rounds=<n> when n is 8 or lower.
   • If the requested --max-rounds is greater than 8, set the effective max round count to 8 and record that cap in the refinement log.
10. For each round from 1 through the effective max round count:

• Start from the current PRD, TDD, and tasks-plan.
• Run the challenger lane first when the round is applicable: round == 1 OR previous_reviewer_round_had_blocker_or_material.
• Send the challenger subagent the current PRD, TDD, tasks-plan, plan key, round number, this skill's challenger standard, any loaded research memo or durable research digest, and any loaded Pro synthesis memo or durable Pro synthesis digest.
• Ask the challenger subagent to pressure-test the artifact set for hidden assumptions, false settled decisions, implementation drift traps, likely failure paths, overengineering, under-specification, and counter-plan pressure.
• The challenger must preserve research-backed and Pro-backed decisions unless it can name a concrete conflict, stale evidence, over-scoped obligation, missing carry-forward, or unsafe assumption with artifact evidence and research/Pro memo or durable digest basis.
• Do not ask the challenger to assign severity, apply fixes, rewrite artifacts, ask the user questions, or continue into another round.
• Require the challenger to return a challenge brief that follows the Challenge Brief Contract below.
• If the challenger finds no material challenge, it must return no_material_challenges_found: yes with a one-sentence rationale instead of inventing objections.
• Send the reviewer subagent the current PRD, TDD, tasks-plan, plan key, round number, this skill's critique standard, the challenger brief when one was produced for the round, any loaded research memo or durable research digest, and any loaded Pro synthesis memo or durable Pro synthesis digest.
• Ask the reviewer subagent to run the normal $plan-refine audit first: a fresh first-principles critique using the analysis rubric plus the audit checks in improve-plan.md; only after that normal audit should it adjudicate any challenge brief.
• The reviewer remains the severity and stop gate. Challenger objections do not become artifact edits, user questions, or another refinement round unless the reviewer classifies them as blocker or material findings.
• Require the reviewer to disposition every challenge_id before edits, stop decisions, or clean completion. If any challenge_id lacks a valid disposition, request a corrected reviewer response for the same round before editing artifacts.
• Do not ask the reviewer to apply fixes, rewrite artifacts, or continue into another round.
• Keep each reviewer round isolated. Do not reuse the same reviewer subagent for later rounds.
• Produce structured findings before editing:
  • id
  • severity: blocker, material, or minor
  • execution_gate: blocks execution, fix before completion, or no action
  • disposition: fix, needs human decision, residual risk, or no action
  • artifact: prd, tdd, tasks-plan, or cross-artifact
  • issue
  • why_it_matters
  • best_fix
  • change_required: yes or no
• Treat blocker as an issue that prevents execution.
• Treat material as an issue that changes behavior, technical direction, sequencing, verification, rollout, safety, or implementer clarity.
• Treat minor as wording, formatting, local clarity, or polish that does not change execution risk.
• Keep blocker / material / minor as the local stop-rule severities, but use finding-disposition.md when reporting material findings outside $plan-refine.
• Set previous_reviewer_round_had_blocker_or_material from reviewer findings only; challenger-only objections do not set it.
• Do not apply challenger-derived fixes unless the reviewer promoted the related challenge_id to a blocker or material finding with disposition: fix. The only exception is a minor coherence edit needed after applying an accepted blocker/material fix.
• Apply fixes only for findings with disposition: fix.
• For needs human decision, stop this pre-execution refinement run before editing and report the exact user decision required. This stop behavior applies to $plan-refine before execution starts; it does not authorize a mid-run stop inside another implementation workflow.
• For residual risk, do not edit around the finding; record the missing evidence, blocker, or external dependency in the refinement log and stop this pre-execution refinement run unless every blocker/material finding has already been fixed or safely downgraded by the reviewer.
• Do not apply no action findings.
• Apply minor fixes only when the edit is necessary to keep the artifacts coherent after material changes with disposition: fix.
• Update only PRD, TDD, tasks-plan, and the refinement log.
• Do not invent exact APIs, schemas, classes, routes, file names, helper names, or test paths unless the source plan or repo inspection already supports them.
• Preserve useful source-plan substance. Do not remove scope just because it is hard.
• Preserve research-backed decisions. Do not remove or weaken research-backed TDR-*, rollout, migration, rollback, verification obligations, or task dependencies unless the refinement log records why the finding is superseded, inapplicable, over-scoped, rejected, or deferred.
• Preserve Pro-backed decisions. Do not remove or weaken adopted Pro findings, Pro-backed TDR-*, rollout, migration, rollback, verification obligations, or task dependencies unless the refinement log records why the finding is superseded, inapplicable, over-scoped, rejected, or deferred.
• Re-run the required audit checks from improve-plan.md after edits.
• Append the round findings, fixes, challenge brief, reviewer challenge dispositions, artifact changes from promoted challenges, challenger-sourced material fixes, accepted residual challenge risks, rejected/deferred challenge reasons, and stop decision to tasks/tmp/plan-refine-<plan-key>.md.

11. When deep research was used, run a final research-carry-forward check after the last artifact edit and before successful completion.
    • Confirm research-backed TDR-*, rollout, migration, rollback, verification obligations, and task dependencies are still present or have a recorded superseded, inapplicable, over-scoped, rejected, or deferred reason.
    • Confirm no artifact being handed to execution still contains evidence_bar_met: no.
    • Record the check result in tasks/tmp/plan-refine-<plan-key>.md.
12. When Pro analysis was used, run a final Pro-carry-forward check after the last artifact edit and before successful completion.
    • Confirm adopted Pro findings, Pro-backed TDR-*, rollout, migration, rollback, verification obligations, and task dependencies are still present or have a recorded superseded, inapplicable, over-scoped, rejected, or deferred reason.
    • Confirm no artifact being handed to execution contains a missing or failed pro_synthesis_complete gate.
    • Record the check result in tasks/tmp/plan-refine-<plan-key>.md.
13. Stop early when a fresh reviewer round finds no blocker or material issues.
14. Stop early and report churn when a round repeats the same finding without a stronger fix, reverses a prior fix without new evidence, or only produces local wording edits after the previous round already satisfied the fixed stop rule.
15. If the effective max round count is reached while blocker or material findings remain, stop and report that the plan is not ready for execution.
    • Keep the refinement log even without --preserve-refine-artifacts.
    • Include the last round's remaining blocker/material findings in the final response.
    • Say this max-round stop is evidence for improving $plan-refine from the concrete example.
16. Before reporting successful refinement or allowing any downstream conversion or implementation workflow to use the artifacts, append the Refinement Completion Stamp below to tasks/tmp/plan-refine-<plan-key>.md.
    • Do not write a successful stamp until at least one fresh reviewer subagent round has completed.
    • Do not write a successful stamp when the log lacks a round section with the reviewer findings, stop decision, and the challenge brief or valid empty challenge brief for every applicable challenger round.
    • Do not write a successful stamp when required challenge dispositions, research carry-forward checks, or Pro carry-forward checks are missing.
    • If the workflow stops before success, write the stamp with plan_refine_complete: no and ready_for_execution: no, then include the stop reason.
17. Clean up tasks/tmp/plan-refine-<plan-key>.md according to invocation context.
    • For standalone $plan-refine, delete the log after a successful run unless --preserve-refine-artifacts is active.
    • For downstream conversion or implementation, keep the log available through execution, final full-branch review, and finalization; delete it during final cleanup only after finalization succeeds unless preservation is active.
    • Keep the log when the run stops with unresolved blockers, material findings, max rounds, or churn.
18. Before returning control, print a short Refinement Findings Summary: material fixes, promoted challenger fixes, remaining blockers, execution gate status, and whether execution is ready.

Critique Standard

Each round must ask whether the artifact set is more executable, not whether it is more verbose.

The critique must cover:

• whether the PRD still states the real user/problem goal and success guardrails
• whether the TDD names the right source of truth, dependencies, failure modes, rollout needs, and verification obligations
• whether the tasks-plan is sequenced so implementation can start without guessing
• whether task outputs and verification steps are concrete enough
• whether every meaningful product requirement has an FR-* ID
• whether every meaningful technical obligation has a TDR-* ID
• whether every task maps back to relevant FR-* and TDR-* IDs
• whether unsupported low-level implementation detail should be removed, softened, or deferred to implementation
• whether any acceptance criterion lacks test or verification coverage
• whether migration, backfill, rollback, security, operational, or frontend evidence requirements are missing where relevant
• whether research-backed decisions from the memo or durable TDD digest were preserved, explicitly superseded, rejected, deferred, or narrowed with a recorded reason
• whether the current plan is over-engineered relative to the actual problem
• whether the current plan is under-specified in ways that would cause implementation drift

Challenger Standard

The challenger is not a second reviewer and must not produce a parallel edit list. Its job is to try to break the apparent plan before the reviewer judges it.

The challenger must focus on:

• hidden assumptions or decisions the artifacts treat as settled without support
• implementation drift traps a worker could plausibly misread
• failure paths, missing constraints, or verification gaps that would make execution fragile
• places where the plan is broader than the actual problem requires
• counter-plan pressure that could simplify or narrow the work without losing the user's goal
• research-backed or Pro-backed decisions only when the challenger can identify a conflict, stale evidence, over-scope, missing carry-forward, or unsafe assumption from the artifacts plus the loaded memo or durable digest

The challenger is read-only, uses a fresh subagent when applicable, and follows the strongest appropriate reasoning tier for refinement work. Its output is advisory input to the reviewer; the reviewer alone decides whether any objection becomes a blocker, material, or minor finding.

Challenge Brief Contract

For every applicable challenger round, the challenge brief must be either a valid empty brief or one or more challenge entries.

A valid empty brief contains only:

• no_material_challenges_found: yes
• rationale: one sentence explaining why no material challenge was found

Do not require challenge ID dispositions for a valid empty brief.

Each non-empty challenge entry must include:

• challenge_id: stable within the round, such as CH-<round>-<n>
• pressure_type
• artifact_refs: PRD, TDD, or tasks-plan references specific enough for the reviewer to inspect
• hidden_assumption_or_failure_mode
• how_it_could_break_execution
• evidence_or_gap
• counter_plan_pressure
• suggested_reviewer_test
• requires_user_decision_candidate: yes or no

The challenger must not include severity, disposition, or artifact rewrite instructions. The reviewer owns severity.

Reviewer challenge dispositions must be keyed by challenge_id and use one of:

• promoted_to_finding
• already_covered
• non_material
• rejected
• superseded
• deferred_with_owner

Record challenge material in the refinement log under stable round sections:

• challenge_brief
• challenger_objections, keyed by challenge_id
• reviewer_dispositions, keyed by challenge_id
• artifact_changes_from_challenges
• rejected_or_deferred_challenges

Disposition rules:

• promoted_to_finding must reference the resulting reviewer finding ID and severity.
• already_covered must reference the existing reviewer finding ID that covers the challenge.
• non_material, rejected, and superseded must include a concise reason.
• deferred_with_owner must name the owner and carry-forward location: a TDD obligation, task-plan step, explicit non-goal, or accepted residual risk.
• deferred_with_owner cannot hide blocker-grade issues; if a challenge would prevent execution, the reviewer must promote it, fix it, or escalate it instead of deferring it.
• Every challenge_id must have exactly one disposition before the main agent edits artifacts, records a clean stop, or reports successful completion.

Stop Discipline

Do not use "the model says it is good enough" as the stop condition.

Stop only from an explicit reason:

• no remaining blocker or material findings from a fresh reviewer subagent
• max rounds reached
• unresolved blocker needs user input
• repeated or contradictory churn
• missing required artifacts

Do not continue rounds just to spend the requested budget when the fixed stop rule has already passed.

Refinement Completion Stamp

Every run must end the refinement log with this stamp. Parent workflows must treat the stamp as the handoff gate; a short risk note without this stamp is not a completed $plan-refine run.

Required stamp fields:

• plan_refine_complete: yes only when the refinement loop completed successfully.
• plan_key: the resolved plan key.
• rounds_run: integer, at least 1 for a successful run.
• fresh_challenger_rounds: integer count of challenger rounds actually delegated. This may be 0 only when no challenger round was applicable after round 1 failure/stop rules; a successful normal run should include the round 1 challenger.
• fresh_reviewer_rounds: integer, at least 1 for a successful run.
• stop_reason: one of clean_reviewer_round, recoverable_churn_no_unresolved_material, max_rounds_unresolved_material, unresolved_blocker_needs_user, missing_required_artifact, missing_required_subagent, failed_research_gate, or failed_pro_gate.
• reviewer_stop_gate: no_unresolved_blocker_or_material, unresolved_blocker_or_material, or not_reached.
• all_challenges_dispositioned: yes, no, or not_applicable.
• research_carry_forward_complete: yes, no, or not_applicable.
• pro_carry_forward_complete: yes, no, or not_applicable.
• ready_for_execution: yes only when plan_refine_complete: yes, fresh_reviewer_rounds >= 1, reviewer_stop_gate: no_unresolved_blocker_or_material, all required challenge dispositions are complete, and required research/Pro carry-forward checks are complete.

Successful stamp template:

## Refinement Completion Stamp

plan_refine_complete: yes
plan_key: <plan-key>
rounds_run: <n>
fresh_challenger_rounds: <n>
fresh_reviewer_rounds: <n>
stop_reason: clean_reviewer_round
reviewer_stop_gate: no_unresolved_blocker_or_material
all_challenges_dispositioned: yes|not_applicable
research_carry_forward_complete: yes|not_applicable
pro_carry_forward_complete: yes|not_applicable
ready_for_execution: yes

Output Contract

Final response must include:

• resolved plan-key
• number of rounds run
• stop reason
• effective max round cap, only when the user requested more than 8 rounds or the run stopped because max rounds were reached
• files changed
• material issues fixed
• challenger-sourced material fixes, when any exist
• unresolved issues or accepted residual risk
• accepted residual challenge risks, when any exist
• whether the plan is ready for downstream conversion or implementation
• completion stamp status, including plan_refine_complete, ready_for_execution, rounds_run, and fresh_reviewer_rounds
• preserved artifact path when --preserve-refine-artifacts is active, when the run stopped before success, or when a downstream workflow is retaining the log through final full-branch review and finalization

Keep the final answer compact. Do not paste the full refinement log unless the user asks for it.