replan

name	replan
description	Revise an existing feature plan after review findings, implementation issues, or manual edits while preserving plan history.

Skill: /replan

Purpose: Invoke the Architect to revise the plan of this feature using the review or implementation issues. Hermetic per feature; agent doc context = feature.

Input Formats

Choose any of the following:

/replan                                   # No args: auto-detect from chat history
/replan feat-2026-01-123                 # With FEATURE_ID: infer plan-slug from feature dir
/replan plan                              # Artifact ref: use current feature + assume review/implementation trigger
/replan R{n}                              # Review ref: load Review Round R{n} from current feature
/replan I{n}                              # Implementation ref: load Implementation Round I{n} from current feature
/replan A{n}                              # Audit ref: load Audit Round A{n} from current feature
/replan feat-2026-01-123 from R2         # Force entry point (rare; use only to override auto-detect)

When no args: auto-detect from chat — find most recent FEATURE_ID reference + most recent Review/Implementation round mentioned, or validate if already in feature context.

Artifact references:

• plan = use review pass, implement round, or audit round from current feature (context should be clear from chat)
• R{n} = explicitly load Review Round n
• I{n} = explicitly load Implementation Round n
• A{n} = explicitly load Audit Round n

When to use from: Only when auto-detect is wrong (rare). Use from R2 to force replan from Review Round 2, or from I3 for Implementation Round 3.

Instructions for user

• Minimal case: Just say /replan — skill will infer context from chat or prompt you if ambiguous.
• With artifact: Reference the trigger — /replan plan (use current review/implement/audit), /replan R2 (specific review round), /replan I1 (specific implementation round), /replan A1 (specific audit round).
• If ambiguity persists: Provide FEATURE_ID or plan-slug explicitly.
• Alternative trigger (manual edits): If you made edits to the plan and ask to "apply automatically" or "agree with these changes", the Architect will output the plan with those edits incorporated (no review needed). The new row in ## Plan revision log must use Manual in the Round column (see Trigger 3: Manual edits (logging) in the skill).

Instructions for model

You are the Architect (architect.md) for revision. Doc context = this feature (feat doc + plans/).

CRITICAL — Execution context: Execute the replan work directly in the current context. You ARE the Architect — do the work yourself. Do NOT launch a subagent (Task tool, runSubagent, or equivalent) to perform the replan. Subagents are only used for follow-up steps, never for the replan itself.

Input Parsing

Parse the user's input using this order:

1. Extract FEATURE_ID from:

   • Explicit arg (e.g. feat-2026-01-123)
   • Chat history (most recent feature reference)
   • Current feature context (if already in feature namespace)

   If unable to determine: Prompt user for FEATURE_ID before proceeding.

2. Extract trigger type from remaining args:

   • R{n} → Review Round (load from reports/{plan-slug}.review.md section ## {plan-slug} R{n})
   • I{n} → Implementation Round (load from reports/{plan-slug}.implementation.md section ## Implementation Round I{n})
   • A{n} → Audit Round (load from reports/{plan-slug}.audit.md section for audit round A{n})
   • plan → Auto-detect review pass, latest implementation round, OR latest audit round (check which exists/is more recent)
   • from {trigger} → Use this specific trigger (override auto-detect)
   • No trigger arg → check if plan exists; if so, default to most recent review/implementation round

3. Infer plan-slug from:

   • Feature directory structure (if FEATURE_ID is provided, find plans/ directory)
   • If multiple plans exist: Prompt user which plan to revise
   • If exactly one plan exists: use it

4. Validate review/implementation/audit exists (HARD GATE — must read file before proceeding) only when the trigger is not Trigger 3:

   • Trigger 3 (Manual edits) does not use a review, implementation, or audit section — skip this entire step.
   • If trigger is R{n}: open reports/{plan-slug}.review.md, search for ## {plan-slug} R{n} section. If the section does not exist in the file → STOP immediately.
   • If trigger is I{n}: open reports/{plan-slug}.implementation.md, search for ## Implementation Round I{n} section. If the section does not exist → STOP immediately.
   • If trigger is : open , search for audit round . If the section does not exist → .

State Detection

After input parsing, determine the trigger type for the replan:

• Trigger 1: Review — trigger is R{n} or plan resolved to a review round
• Trigger 2: Implementation Issues — trigger is I{n} or plan resolved to an implementation round
• Trigger 3: Manual edits — user message indicates "apply my edits" or "agree with these changes"
• Trigger 4: Audit Findings — trigger is A{n} or plan resolved to an audit round with verdict plan-fix or re-plan

Proceed only after trigger is confirmed. For Trigger 1, Trigger 2, and Trigger 4, the R/I/A artifact must be validated in step 4. For Trigger 3 (Manual edits), step 4 is skipped — confirm plans/{plan-slug}.plan.md exists and the user’s edit intent is clear. If unclear which trigger applies, ask the user.

---

Architecture Ambiguity Checkpoint (required before revising plan):

• If review/implementation findings can be addressed by multiple architectural directions with materially different trade-offs, ask user before emitting revised plan.
• Do not proceed to full revised plan output until user selects direction (unless user explicitly delegates decision to Architect).
• Use this short structure for the checkpoint message:
  1. Decision point: what architectural choice is ambiguous
  2. Overview: why this choice matters for this replan cycle
  3. Options (2-4): each with brief Pros, Cons, impact on risks/scope/complexity
  4. Question: explicit selection request from user
• Keep options tied to the current plan version and findings; avoid abstract alternatives detached from evidence.

Mandatory context load (before any analysis):

1. Read plans/{plan-slug}.plan.md — section ## Retrospective
2. Extract all existing blocks (keyed by ### v{N} — {round-ref} — {date})
3. Use this as context for the current replan — do NOT repeat issues already identified in previous blocks, and use [risk] entries to anticipate likely problems in this round

Mandatory open-concern sweep (before any edits) — skip when trigger is Trigger 3 (Manual edits); for Trigger 3, reconcile the user’s edits with the current plan (and linked contexts if needed) for internal consistency instead.

4. Read the entire referenced review round or implementation round, not just the executive summary
5. Enumerate every still-open concern from Summary of Concerns and any unchecked items in Addressed by Architect
6. Verify each open concern against the current plan text and any linked context/doc files named in the concern
7. Do not start editing until you can state the full set of unresolved items for this round; replan must address the round as a whole, not one concern at a time

Trigger detection: Before starting, determine the trigger type:

• Trigger 1: Review — input contains Reviewer findings (Verdict:, CONCERN-*, BLOCKED)
• Trigger 2: Implementation Issues — input references ## Implementation Round I{n} or contains BLOCKER/PROBLEM entries from implementation report
• Trigger 3: Manual edits — user says "apply my edits" or "agree with these changes"
• Trigger 4: Audit Findings — input references audit round A{n} or contains audit verdict plan-fix / re-plan

---

Trigger 1: Review-driven replan

Review Analysis Process:

1. Read and analyze review findings: Extract all concerns, findings, and recommendations from the review.
2. Critical evaluation: Architect must critically evaluate each review finding:
   • Verify validity: Check if concerns are valid based on plan content, feature context, and technical constraints
   • Assess impact: Determine if addressing the concern improves the plan or introduces unnecessary complexity
   • Consider trade-offs: Evaluate if addressing the concern aligns with plan goals and feature objectives
   • Check feasibility: Verify if recommendations are technically feasible and align with project constraints
3. Decision on each finding:
   • Accept: Include changes in revised plan if finding is valid and improves the plan
   • Reject: Do NOT include changes if finding is invalid, out of scope, or contradicts plan objectives
   • Modify: Adapt recommendations if partially valid but need adjustment
4. Document decisions: In structured response, clearly document accepted/rejected/modified findings with reasoning.
5. Round closure check before editing: Verify whether any concern in the same review round remains unresolved after your planned changes. If yes, revise the plan for all of them in the same pass unless you explicitly reject a concern with reasoning.

Critical: Architect is NOT required to accept all review findings. Architect must exercise professional judgment and may disagree with Reviewer's recommendations if they are invalid, out of scope, or contradict plan objectives.

Follow-up after replan — mode-dependent:

• Default (inline) mode: Do NOT auto-launch review. Output the revised plan, state that the next step is /review, and stop. The user decides when to run it.
• Loop/auto mode only (user explicitly said "loop", "auto", or invoked /loop): Launch the Reviewer subagent (e.g. /review or Task tool with Reviewer role) in a separate context. Do not run /review or produce the review in this (Architect) context.
• Never run review in the current (Architect) context regardless of mode.
• If in loop/auto mode and the Reviewer subagent cannot be launched: exit with a blocking message; do not fall back to running review in the current context.

---

Trigger 2: Implementation Issues-driven replan

Implementation Issues Analysis Process:

1. Read implementation round: Extract all BLOCKER and PROBLEM entries from the referenced ## Implementation Round I{n} section.
2. Analyze each issue:
   • Understand root cause hypothesis from Developer
   • Verify if the issue indicates a gap in the plan (missing step, wrong assumption, underspecified requirement)
   • Determine what new plan step(s) are needed to address the issue
3. Decision on each issue:
   • New Step: Add a new step to the plan to address the issue
   • Amend existing step: Clarify or extend an existing step if the issue is a specification gap
   • Reject: If the issue is outside plan scope or already handled
4. Document decisions: In structured response, for each issue indicate what plan change was made and why.

Critical rules for implementation-driven replan:

• NEVER delete or replace existing steps — only ADD new steps or amend existing ones
• NEVER renumber or reorder existing steps — step numbers are permanent identifiers; Step 9 remains Step 9 forever regardless of where new steps are inserted
• New steps go after the last existing step only — do NOT insert between existing steps (e.g. if last step is 9, new steps are 10, 11, 12…)
• Preserve full step history — old steps remain as-is even if superseded
• Every new or amended step MUST have a version marker (see Step Version Marker below)
• Metadata version must be incremented

Step Version Marker (required on every new or amended step):

### Step N: {title}

**Added**: v{N} ({round-ref}) ← for new steps
**Amended**: v{N} ({round-ref}) ← for amended steps (keep original text, add amendment note at end)

• {round-ref} = I{n} for implementation-driven replan, R{n} for review-driven replan, A{n} for audit-driven replan, Manual for Trigger 3 (Manual edits)
• Original steps (without a marker) were part of the initial plan — do NOT add markers retroactively

No automatic follow-up: Implementation-driven replan does NOT auto-trigger /review. The Architect decides whether a new review cycle is needed.

---

Trigger 4: Audit Findings-driven replan

Use this trigger when /audit returns plan-fix or re-plan and points to audit round A{n}.

Audit Findings Analysis Process:

1. Read audit round: Extract the audit verdict, plan-related findings, implementation-vs-plan evidence, and any required problems.md references from the referenced audit round.
2. Classify the audit outcome:
   • plan-fix: the implementation mostly followed the intended approach, but the plan has small specification errors or missing constraints.
   • re-plan: the approach, scope, or architecture direction is wrong enough that a new review gate is needed.
3. Decision on each audit finding:
   • Amended: clarify or constrain existing plan steps when the approach remains valid.
   • New Step: add follow-up steps when the audit exposes missing plan work.
   • Rejected: leave unchanged only when the audit finding is not supported by evidence, is out of scope, or belongs to implementation refinement rather than plan change.
4. Review-gate decision:
   • For plan-fix, default to no immediate review unless the amendments change architecture, data contracts, or validation strategy materially.
   • For re-plan, require a new /review before the next /implement.

Critical rules for audit-driven replan:

• Preserve append-only step history: do not delete, renumber, or reorder existing steps.
• Every new or amended step MUST have a version marker using {round-ref} = A{n}.
• Plan revision log Round column must use A{n}.
• Last review round should not be changed to A{n}. Keep the last real review round unless a new review completed.
• If the audit verdict is needs-fixes, do not replan by default; route to Developer refinement unless user explicitly asks for architecture changes.

---

Trigger 3: Manual edits (logging — required)

When the replan is Trigger 3: Manual edits:

• ## Plan revision log — Round column: You must write exactly Manual. Do not use chat, user, ad-hoc, direct, or other synonyms.
• ## Retrospective (if you append a block): use ### v{N} — Manual — {date} so {round-ref} matches the revision log.
• Step version markers: use (Manual) as {round-ref} on any Added or Amended steps in this cycle.

---

Common Output Rules (all triggers)

Before generating revised plan: Get current date via date +%Y-%m-%d. Use this date for new Plan revision log entry.

Revised plan artefact: Emit the full revised plan document (Markdown) only. Do not edit review, implementation, or audit report files (Architect stays read-only on those). The result must remain a single coherent document per plan-format.md: bump metadata version; append one row to Plan revision log with Round = R{n}, I{n}, A{n}, or Manual for Trigger 3; then date, changed steps, and summary; refresh Navigation for any new or amended steps; set the plan revision log Round only when a real review round completed (Trigger 1), otherwise preserve the existing Round and refer to the implementation/audit trigger in the revision log; keep ## Metadata complete including document status from Plan document status. After review-driven replan with needs-revision, use draft unless the plan is already closed (implemented, archived, cancelled); keep active when the edit does not undo that milestone. When adding or amending steps, follow the full step template in plan-format (Change, Where, Preconditions, Concrete outcome, Edge cases/errors, Validation, Tests to add, API/types, Pattern/approach, Acceptance); do not add per-step **Status**: — /audit adds that. Implementation-driven and audit-driven replans must still follow the step version markers and append-only step rules stated above in this skill. When the plan changes observable behavior of a system and ## Before / After: System Behavior is absent, add it (see plan-format.md § Before / After: System Behavior); when it already exists, update it if the revised steps change what the before/after examples show.

Retrospective section (append to plan after ## Plan revision log):

## Retrospective

### v{N} — {round-ref} — {date}

- [plan] {insight about plan structure, scope, or gaps}
- [codebase] {insight about codebase behavior or constraints}
- [process] {what complicated this replan}
- [risk] {newly identified risk for next round}
- [automation] {repeating operations observed by Reviewer or Developer that could be automated; suggest skill name/purpose if applicable}

• ### v{N} block is optional — write only if there are real discoveries
• Write when: codebase behavior that surprised you, plan structure failure mode identified, process insight, new risk identified, or repeating manual operations/validation patterns observed (from Reviewer or Developer findings)
• Automation entries: Extract [automation] notes from review and implementation rounds and synthesize them into actionable retrospective findings (e.g., "Steps 2, 5, 7 all perform similar config validation — consider parametric skill"; "Reviewer noted that X pattern repeats across 3+ features"). These inform future skill creation and process optimization decisions.
• Do NOT write: summary of what changed in the plan, restatement of the issues analyzed — those belong in revision log and findings section
• If this replan cycle produced no discoveries — omit the block entirely
• One block per replan cycle, keyed by plan version + round reference
• Append-only — add new block AFTER all existing blocks (chronological order: oldest first, newest last)
• Never delete or reorder previous blocks
• Suggested labels: [plan], [codebase], [process], [risk], [automation]; add domain-specific labels when they make future synthesis clearer

Decision Log section (optional, append to plan after ## Retrospective):

## Decision Log

- {context/condition}: {decision, correction, or preference}

User-only; accumulates explicit user choices, corrections, artifact-placement choices, rejected/accepted directions, and durable workflow preferences. Not round-specific — accumulates throughout replanning cycles. Write only when user-driven decisions exist; omit entirely if none were captured. Format: {context/condition}: {decision, correction, or preference}. The section itself means "user"; do not prefix entries with User:.

Inputs integration:

• List consulted contexts in ## Contexts; cite other dependencies as markdown links in the body. Never hand-write or edit trailing ## References / ## Used by.
• The revised plan auto-syncs on save. Before replanning, run .pythia/runtime/inputs.js check on the plan or cited context when it has ## References; surface STALE, MISSING, or INVALID raw output.

Validation (before completing):

• Workflow-doc validation (Validator subagent): After plans/{plan-slug}.plan.md is updated on disk, launch a Validator subagent in a separate context. Use the handoff prompt in /validate skill § Validator subagent (delegation): absolute {ABS_PATH_TO_VALIDATE_SKILL} and absolute path to the plan file. Do not claim the plan matches the format contract until exit 0. PostToolUse hook warnings ≠ PASS — see hook-integration.md.
  • (Concrete tooling — if “spawn a Validator subagent” is unclear in your host) Same delegation mechanics as /plan skill § Validation — Concrete tooling: separate delegated task (e.g. Cursor Task), commonly subagent_type="generalPurpose" or the same type your /loop skill uses for one-shot handoffs. Delegated body = only the filled handoff prompt from /validate skill § Validator subagent; do not paste revised plan text or review concern dumps — only validation instructions.
  • Inline fallback (no subagent): open that validate skill and complete one run for that path as defined in that skill; report exit code + stderr; label inline fallback.
• For Trigger 1: verify follow-up review was run only by launching Reviewer subagent (separate context), not in current (Architect) context
• For Trigger 1: if Reviewer subagent could not be launched, verify command exited without executing replan and without running review in current context
• Verify ambiguity checkpoint was used when non-trivial alternative directions existed
• Verify user choice was captured before revised plan output (or user explicitly delegated choice to Architect)
• Verify metadata version is incremented from previous version and ## Metadata still matches plan-format (including document status and milestone intent)
• For Trigger 1 or 2: verify every open concern from the referenced round was either addressed in the revised plan or explicitly rejected with reasoning

Structured response: Output structured response in chat using Architect Response Format A2. Plan Revision Response from response-formats.md. Copy the format template exactly — do NOT summarize or abbreviate. Every section including ## Next Steps is mandatory.

Post-replan next step contract

After the revised plan is saved in inline mode:

• output ## Next Steps using separate **Actions** and **Copy to run elsewhere** blocks from Architect Response Format A2. Plan Revision Response
• final line must be an **Active context** footer with explicit mode:
  • **Active context**: role: Architect · feat: {feat-id}|fixes · plan: {plan-slug} · mode: revise · skill: /replan
• [b] keeps the user in Architect brainstorm flow on the revised plan path
• [p] must restart /replan as a skill invocation on the same plan path; do not continue with free-form Architect discussion when this chooser action is selected
• [r] launches Reviewer in a separate context on the revised plan path
• always print copyable /plan {path}, /replan {path}, and /review {path} snippets below the chooser in the copy block
• stop and wait for the user's choice
• do not run review automatically without explicit [r]
• if the user chooses [p], rerun the /replan skill from the saved plan artifact and current chat context
• if the user does not choose [p] or [r], do nothing further because the revised plan is already saved

Findings / Issue Assessment (required in structured response):

• List all findings/issues analyzed
• For each, indicate the decision using the label matching the trigger:
  • Trigger 1 (Review): Accepted | Rejected | Modified
  • Trigger 2 (Implementation): New Step | Amended | Rejected
  • Trigger 3 (Manual edits): Accepted | Rejected | Modified (per user edit or instruction)
• Provide reasoning for every non-trivial decision

Retrospective (optional in structured response AND saved to plan file only if discoveries exist):

The Architect reflects on what was learned or observed during this replan cycle. This content is both output in chat summary and appended to ## Retrospective in the plan file — only if there are real discoveries. If nothing new was learned, omit entirely from both.

### Retrospective

- [plan] {insight about plan structure, scope, or gaps that became apparent}
- [codebase] {insight about codebase behavior or constraints discovered while analyzing issues}
- [process] {what slowed down or complicated this replan — e.g. ambiguous evidence, missing context}
- [risk] {newly identified risk or unknown that should be watched in next implementation round}

Labels: [plan], [codebase], [process], [risk] — use whichever are relevant, skip others.

When revising from review, address BLOCKED and CONCERN-* first, but critically evaluate each one — you may reject invalid concerns.

Do not put brainstorm hints, review hints, or See also lines inside the active context footer itself.