iterating-plans

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:

• Read the entire existing plan before making changes
• Ran research tasks if technical understanding was needed
• Confirmed understanding with user before editing
• Made precise edits without unnecessary rewrites
• Maintained consistency with existing structure
• Updated all affected sections (approach, criteria, references)
• Preserved Automated vs. Manual verification split
• All file:line references are accurate
• No open questions remain in the updated plan
• User is satisfied with changes