name: iterate-plan
description: Update existing implementation plans through user feedback with thorough research and validation. Also migrates old checkbox-based plans to the new Task tools system. This skill should be used when iterating on implementation plans, updating plans based on new requirements, refining technical approaches in existing plans, migrating old plans to Task tools, or when the user wants to modify a previously created plan file. Triggers on requests like "update the plan", "change the implementation approach", "iterate on this plan", "migrate to new system", or when feedback is provided about an existing plan document.

Iterate Plan

Overview

This skill enables intelligent iteration on existing implementation plans. Rather than rewriting plans from scratch, it makes surgical, well-researched updates while preserving the plan's existing structure and quality standards.

Progress Tracking with Task Tools

This skill uses Claude Code's native Task tools for progress tracking.

When iterating on plans, you must keep Tasks synchronized with plan changes:

Important: The plan's task_list_id in metadata links to its Tasks. Always verify you're updating the correct task list.

Migrating Old Plans to Task Tools

Use this process when a plan lacks task_list_id in its metadata.

Old plans used checkbox-based progress tracking ([x] / [ ]). The new system uses Task tools. When you encounter an old plan, migrate it.

Detecting Old Plans

An old plan has:
- No task_list_id in YAML frontmatter
- Checkbox-based progress: - [x] Task completed / - [ ] Task pending
- No reference to Task tools

Migration Process

Step M1: Generate task_list_id

Create an ID from the plan filename:

docs/plans/2024-03-15-user-auth.md → plan-2024-03-15-user-auth
docs/plans/api-refactor.md → plan-api-refactor

Step M2: Add metadata to plan

Add or update the YAML frontmatter:

---
task_list_id: plan-2024-03-15-user-auth
migrated_from_checkboxes: true
migration_date: 2026-01-25
---

Step M3: Create Tasks for each phase

For each phase in the plan:

TaskCreate:
  subject: "Phase N: [Phase Name]"
  description: "[Phase objective from plan] - Plan: [plan file path]"
  activeForm: "Implementing Phase N: [Name]"

Step M4: Determine phase status from checkboxes

Analyze existing checkboxes to determine status:

TaskUpdate:
  taskId: [phase task]
  status: "completed" | "in_progress" | "pending"

Step M5: Set up dependencies

Create sequential dependencies:

TaskUpdate:
  taskId: [phase-2-task]
  addBlockedBy: [phase-1-task]

TaskUpdate:
  taskId: [phase-3-task]
  addBlockedBy: [phase-2-task]

Step M6: Preserve checkboxes as reference

Do NOT remove checkboxes from the plan. They serve as historical record. Add a note:

> **Note**: This plan has been migrated to Task tools for progress tracking.
> Checkboxes below are preserved for reference but progress is now tracked via `TaskList`.
> Task List ID: `plan-2024-03-15-user-auth`

Migration Example

Before (old plan):

# Implementation Plan: User Authentication

## Phase 1: Database Schema
- [x] Create users table
- [x] Add password hash column
- [x] Create sessions table

## Phase 2: Auth Service
- [x] Implement password hashing
- [ ] Implement login endpoint
- [ ] Implement logout endpoint

## Phase 3: Testing
- [ ] Unit tests for auth service
- [ ] Integration tests

After (migrated plan):

---
task_list_id: plan-user-authentication
migrated_from_checkboxes: true
migration_date: 2026-01-25
---

# Implementation Plan: User Authentication

> **Note**: This plan has been migrated to Task tools for progress tracking.
> Checkboxes below are preserved for reference but progress is now tracked via `TaskList`.
> Task List ID: `plan-user-authentication`

## Phase 1: Database Schema
- [x] Create users table
- [x] Add password hash column
- [x] Create sessions table

## Phase 2: Auth Service
- [x] Implement password hashing
- [ ] Implement login endpoint
- [ ] Implement logout endpoint

## Phase 3: Testing
- [ ] Unit tests for auth service
- [ ] Integration tests

Tasks created:

Tasks (1 done, 2 open):
  ✓ #1 Phase 1: Database Schema
  ● #2 Phase 2: Auth Service (in_progress) › blocked by #1
  ◻ #3 Phase 3: Testing › blocked by #2

When to Migrate

Migrate automatically when:
- User runs /iterate-plan on an old plan
- User runs /implement-plan on an old plan
- User explicitly asks to "migrate" or "update to new system"

Present migration summary to user:

📋 Plan Migration Required

This plan uses the old checkbox-based progress tracking.
I'll migrate it to the new Task tools system.

Phases detected: 3
  - Phase 1: Database Schema (completed - all checkboxes checked)
  - Phase 2: Auth Service (in progress - partial checkboxes)
  - Phase 3: Testing (pending - no checkboxes checked)

Proceed with migration? (Tasks will be created, checkboxes preserved)

Initial Input Handling

Parse the user's request to identify two required elements:

1. Plan file path - The location of the existing implementation plan
2. Requested changes - What modifications the user wants

Handle these scenarios:

Six-Step Iteration Process

Step 1: Understand the Current Plan

Read the complete plan file and thoroughly understand:
- Overall structure and organization
- Current technical approach and decisions
- Success criteria (both automated and manual)
- Dependencies and relationships between sections
- Any existing constraints or trade-offs documented
- The task_list_id in plan metadata (links to Task tools progress)

Check for old plan format:

IF plan has no task_list_id in frontmatter:
  → Plan needs migration (see "Migrating Old Plans to Task Tools")
  → Present migration summary to user
  → Perform migration before proceeding with iteration

Check existing Tasks (for migrated/new plans):

TaskList: View current tasks for this plan

Note which phases:
- Are already completed (don't modify completed work without good reason)
- Are in progress (coordinate changes carefully)
- Are pending (safe to modify)
- Are blocked (check what's blocking them)

Document the sections that will likely need modification based on the feedback.

Step 2: Research If Needed

Critical: Only spawn research tasks if the changes require new technical understanding.

When research is necessary, use specialized sub-agents with highly specific instructions:

Research Task Template:
- Agent type: codebase-locator | codebase-analyzer | Explore
- Specific directories to examine
- Exact patterns or code to find
- Required output format (file:line references)

Research scenarios that warrant sub-agent spawning:
- Changes involve unfamiliar parts of the codebase
- New integrations or dependencies need validation
- Technical feasibility of proposed changes is uncertain
- Alternative approaches need evaluation

Do NOT research when:
- Changes are cosmetic or structural (reordering, rewording)
- The modification is already well-understood
- Feedback is about plan formatting, not technical content

Step 3: Present Understanding Before Changes

Before making any modifications, present:

1. Interpretation of Feedback
2. Restate what changes are being requested

3. Confirm understanding of the user's intent

4. Research Findings (if research was performed)

5. Key discoveries with file:line references

6. Technical implications for the plan

7. Planned Modifications

8. List specific sections that will change
9. Describe the nature of each change
10. Note any sections that will remain unchanged

Wait for user confirmation before proceeding to Step 4.

Step 4: Make Surgical Edits

Update the plan using Edit tool with these principles:

Structural Integrity
- Maintain existing heading hierarchy
- Preserve section organization patterns
- Keep consistent formatting throughout

Content Quality
- Ensure changes align with surrounding context
- Update all related sections (e.g., if changing approach, update affected tasks)
- Maintain traceability between requirements and implementation tasks

Success Criteria Standards
- Automated Verification: Commands that can be run (tests, lints, builds)
- Manual Verification: Human-observable behaviors requiring testing
- Never mix these categories; keep them distinctly separated

Edit Scope
- Change only what is necessary to address the feedback
- Avoid "while I'm here" improvements unless explicitly requested
- Preserve author's voice and existing explanations where possible

Step 5: Synchronize Tasks

Critical: Keep Tasks aligned with plan changes.

For added phases:

TaskCreate:
  subject: "Phase N: [New Phase Name]"
  description: "[Phase objective] - Plan: [plan file path]"
  activeForm: "Implementing Phase N: [Name]"

TaskUpdate:
  taskId: [new task]
  addBlockedBy: [previous phase task ID]

For removed phases:

# If phase was never started:
TaskUpdate:
  taskId: [removed task]
  status: "completed"
  description: "[Original description] - REMOVED: [reason]"

# Update dependencies of subsequent phases
TaskUpdate:
  taskId: [next phase]
  addBlockedBy: [new predecessor]

For reordered phases:

# Clear old dependencies and set new ones
TaskUpdate:
  taskId: [moved phase]
  addBlockedBy: [new predecessor IDs]

For renamed/modified phases:

TaskUpdate:
  taskId: [phase task]
  subject: "Phase N: [New Name]"
  description: "[Updated description]"

Step 6: Present Changes and Invite Iteration

After editing, present:

1. Summary of Changes Made
2. What was modified in the plan and why
3. Any dependencies that were updated as a result

4. Task changes made (added, removed, reordered)

5. Current Task Status

6. Show updated TaskList output

7. Highlight any dependency changes

8. Invitation for Further Iteration

9. Ask if the changes meet expectations
10. Offer to refine any sections further

Critical Guidelines

Be Skeptical

• Question whether changes are truly needed
• Verify technical claims through research, not assumptions
• Challenge feedback that may be based on misunderstanding

Be Surgical

• Minimize edit scope to exactly what's needed
• Prefer targeted edits over section rewrites
• Preserve existing content that isn't directly affected

Be Thorough

• Update all sections affected by a change (dependencies, success criteria, etc.)
• Ensure internal consistency after modifications
• Verify no orphaned references remain

Be Interactive

• Confirm understanding before making changes
• Present planned modifications before execution
• Seek feedback after changes are complete

Never Update with Open Questions

Do NOT update the plan with unresolved questions.

If research reveals ambiguity or multiple valid approaches:
1. Present the options to the user
2. Explain trade-offs for each
3. Wait for direction before proceeding

Quality Checklist

Before considering iteration complete, verify:

• [ ] All requested changes have been addressed
• [ ] Success criteria remain measurable and categorized (automated vs manual)
• [ ] No broken references or orphaned sections
• [ ] Plan remains internally consistent
• [ ] Technical approach is validated (if changes were technical)
• [ ] Tasks synchronized (added/removed/reordered to match plan)
• [ ] Task dependencies correct (blockedBy relationships updated)
• [ ] task_list_id present in plan metadata (add if missing)
• [ ] User has confirmed the changes meet their needs

For migrated plans, also verify:
- [ ] task_list_id added to YAML frontmatter
- [ ] migrated_from_checkboxes: true in frontmatter
- [ ] Migration note added to plan body
- [ ] Task status matches checkbox state (completed/in_progress/pending)
- [ ] Original checkboxes preserved for reference

Task Synchronization Rules

Never leave Tasks out of sync with the plan. The Task list is the source of truth for progress, and the plan is the source of truth for specifications.