| name | iterating-plans |
| description | Use when an existing implementation plan needs changes before or during execution. Triggers: update the plan, change the plan, add a phase, revise scope, incorporate experiment results. |
Iterating Plans
Revise an existing docs/rse/specs/plan-*.md with focused, surgical edits that
preserve good content and maintain internal consistency.
Interaction mode
This skill leans Collaborative by default. For the full Collaborative-vs-Direct protocol and override rules, see the Interaction Modes reference in the ai-research-workflows:using-research-workflows skill.
Starting the skill
If the plan file or the requested change is missing, enter Collaborative mode
and ask for it (list recent plans with ls -lt docs/rse/specs/plan-*.md .agents/plan-*.md 2>/dev/null | head -5).
Process
Step 1: Read and understand the current plan
Read the entire plan completely (avoid partial reads). Identify:
- Number of phases, current scope, defined success criteria, implementation
approach, and included references.
Parse the requested change: adding/removing phases or tasks, updating success
criteria, changing technical approach, incorporating new information, splitting
or reordering phases.
Determine whether the change requires codebase research:
- Research needed — changes introduce new technical requirements or alter
approach
- No research needed — structural changes (reordering, splitting),
clarifications, or minor scope adjustments
Step 2: Research if needed
Only if changes require new technical understanding:
- Investigate in parallel: how a new requirement is currently handled, examples
of a pattern the new phase should follow, dependencies for a new component,
tests covering a related area.
- Wait for all research to complete before proceeding.
- Synthesize: what files need adding to tasks, what patterns to reference, what
success criteria to add, what risks to note.
Step 3: Confirm understanding before editing
Before making any changes, present:
I've read the plan and understand you want to [summary of requested changes].
Current state:
- Phases: [list]
- Scope: [summary]
Proposed changes:
- [Change 1]
- [Change 2]
Sections affected:
- [Section 1]
- [Section 2]
[If research was done] Key findings:
- [Finding]
Does this match what you're looking for?
Get user confirmation. If the user says no, clarify and adjust; only proceed on yes.
Step 4: Update the plan — surgical edits
Make focused, precise edits to the plan in place (at its existing path — docs/rse/specs/plan-*.md, or a legacy .agents/plan-*.md).
Good edits: add a new phase section between existing phases; update specific
success criteria items; modify task descriptions within a phase; add file
references to existing tasks.
Bad edits: replace the entire plan; rewrite sections that don't need
changes; change formatting or structure unnecessarily.
Maintain existing structure unless explicitly changing it: same phase format,
same task description pattern, same reference style, same level of detail.
When adding tasks or phases include specific path/to/file.ext:123-145
references — research actual code locations if needed.
When scope changes update success criteria (add/remove items) and preserve the
Automated vs. Manual verification split:
### Automated Verification
[Commands and checks that run without human intervention]
### Manual Verification
[Steps requiring human testing and judgment]
Ensure consistency: new phases follow existing structure; scope changes update
"What We're NOT Doing"; approach changes update "Implementation Approach"; new
tasks reference actual codebase examples.
After editing, run a consistency scan: phase numbering is monotonic and
contiguous; every cross-reference (to a phase, file, or success criterion) still
resolves; no task references a type, function, or file removed elsewhere; and the
Automated/Manual split is intact. Fix any drift before presenting.
When a change alters the technical approach or adds a results-producing phase,
re-check the plan's research criteria too — reproducibility, seeds/provenance,
and numerical-correctness success criteria (ai-research-workflows:ensuring-reproducibility,
ai-research-workflows:hardening-research-code) — so an edit doesn't silently
invalidate them.
Step 5: Present the changes
# Plan Updated
Changes to `docs/rse/specs/plan-[slug].md`:
## Changes Made
- [Change 1 — specific section]
- [Change 2 — specific section]
## Impact
- [How changes affect implementation]
- [New/removed success criteria]
Would you like any further adjustments?
If the user wants more changes, re-read the plan first and apply the same process.
Important guidelines
Be skeptical — push back on changes that conflict with existing phases;
question vague feedback ("when you say 'more robust', do you mean...?"); verify
technical feasibility with code research before adding tasks.
Be surgical — edit only what needs changing; don't reformat or rewrite for
style.
Be thorough — read the entire plan before editing; never guess at file paths.
No open questions — this is a BLOCKING REQUIREMENT. If a requested change
raises questions, ask or research immediately. Do NOT update the plan with
unresolved questions; plans must be complete specifications.
Common iteration patterns
For the five detailed patterns (adding a phase, updating success criteria,
adjusting scope, incorporating experiment results, splitting a complex phase),
see references/iteration-patterns.md.
Common Mistakes
- Rewriting whole sections instead of surgical edits — only change what the
user asked to change; preserve structure, formatting, and unaffected content.
- Editing without confirming first — always present the proposed changes and
get user confirmation before writing to the plan file.
- Leaving open questions in the plan — if a requested change raises
unresolved questions, ask or research immediately; never commit ambiguity to
the plan.
- Skipping research when technical changes require it — changing approach or
adding phases that reference new code requires investigating the codebase first.
- Breaking internal consistency — after edits, verify that phase numbering,
scope statements, success criteria, and references are still coherent.
Cross-references
After iterating, execute with the ai-research-workflows:implementing-plans skill. Incorporate
docs/rse/specs/experiment-*.md (or legacy .agents/experiment-*.md) results when revising the technical approach.
Quality checklist
Before completing, verify:
