Start Iteration

Starting an Iteration

Overview

Begin a new iteration for an open-ended goal by loading context from previous iterations, setting up the workspace, and preparing to continue progress.

Core principle: Each conversation is one iteration. Load recent state, understand where you left off, continue the journey.

When to Use

Use this skill when:

• User runs /start-iteration command
• Beginning work on an ongoing open-ended goal
• Need to load context from previous conversation sessions

DO NOT use for:

• Closed goals with definition of done (use ed3d-plugins plan-and-execute workflow instead)
• First-time brainstorming (use brainstorming skill first)
• One-off tasks that don't need iteration tracking

Quick Reference

Process

Step 1: Detect Existing Goal

Check if a goal already exists in the current project:

# Use Glob to check for autonomy directory
pattern: "autonomy/*/goal.md"

If goal.md found:

• Extract goal name from directory path
• Proceed to Step 2 (Load Recent Context)

If no goal found:

"No autonomy goal found in this project.

Use `/create-goal` to set up a new open-ended goal first, then run `/start-iteration` to begin work."

Stop here - cannot start iteration without a goal.

Step 2: Load Recent Context

For existing goals, load context from recent iterations:

1. Count iterations:

   # Use Glob to find iteration files
   pattern: "autonomy/[goal-name]/iteration-*.md"
   

2. Determine iteration number:

   • Count existing files: N
   • This iteration will be: N+1

3. Dispatch journal-reader agent:

   Task tool with subagent_type: "autonomy:journal-reader"
   Prompt: "Read last 3-5 iterations for goal '[goal-name]' and extract:
           - Current state
           - Open blockers and questions
           - Recent progress
           - Key metrics
           - Recommended next steps"
   Model: haiku
   

4. Wait for agent response with structured context

Step 3: Load Older Context (if >5 iterations)

If more than 5 iterations exist, read the existing summary.md for older context. Do NOT update or regenerate it here.

1. Read summary.md if it exists:

   file: "autonomy/[goal-name]/summary.md"
   

   • If present: incorporate into the state presented to the user.
   • If absent or stale: proceed without it. It will be (re)generated at the end of the next milestone iteration (5, 10, 15, …).

DO NOT dispatch journal-summarizer at the start of an iteration. summary.md is owned by the end-iteration skill and is only updated at the end of every 5th iteration (5, 10, 15, 20, …). Updating it here causes redundant rewrites, wastes tokens, and risks summarizing iterations that have not concluded yet.

Step 4: Present State to User

Combine findings from journal-reader (and summary if applicable):

**Iteration [N] started for goal: [goal-name]**

## Current State
[From journal-reader: most recent ending state]

## Recent Progress (Last 3-5 Iterations)
[Condensed summary of what was accomplished]

## Open Blockers
- [Blocker 1]
- [Blocker 2]

## Open Questions
- [Question 1]
- [Question 2]

## Key Metrics
- [Metric]: [Current value] (was [previous value])

## Recommended Next Steps
[From previous iteration's suggestions]

---

**Ready to continue. What should we work on this iteration?**

Step 5: Create Initial Journal Entry

Before beginning work, create the journal file for this iteration:

1. Determine iteration number and filename:

   • Count: N existing iterations
   • This iteration: N+1
   • Filename: iteration-NNNN-YYYY-MM-DD.md (today's date)

2. Prompt user for iteration intention:

   "What do you want to accomplish this iteration?
   
   This helps keep us honest about the goal. We'll check against this intention when ending the iteration."
   

3. Write initial journal entry:

# Iteration NNNN - YYYY-MM-DD

## Beginning State
[From journal-reader output or user context:
- Current progress summary
- Known blockers from previous iteration
- Open questions being addressed
- Current metric values if tracked]

## Iteration Intention
[User's stated intention for this iteration]

## Work Performed

### Skills & Workflows Used
[Will be filled during checkpoint or ending]

### Key Decisions Made
[Will be filled during checkpoint or ending]

### Artifacts Created/Modified
[Will be filled during checkpoint or ending]

### External Context Gathered
[Will be filled during checkpoint or ending]

### Reasoning & Strategy Changes
[Will be filled during checkpoint or ending]

### Blockers Encountered
[Will be filled during checkpoint or ending]

### Open Questions
[Will be filled during checkpoint or ending]

## Ending State
[Will be filled when ending iteration]

## Iteration Metadata
[Will be filled when ending iteration]

4. Write file to: autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md

Step 6: Ready to Work

1. Create TodoWrite tracker for current iteration work:

   TodoWrite with todos:
   - [First task based on next steps or user intention]
   - [Additional tasks as identified]
   

2. Begin work on the goal

Important Notes

Iteration Numbering

• Use 4-digit zero-padded numbers: 0001, 0002, ..., 0999, 1000
• Format: iteration-NNNN-YYYY-MM-DD.md
• Date is when iteration occurred (today)

Context Loading Strategy

• Iterations 1-5: Load all in detail with journal-reader
• Iterations 6+: Load last 3-5 in detail, older iterations via summary
• Update summary every 5 iterations (5, 10, 15, 20, etc.)

Agent Delegation

Always use Task tool to dispatch journal-reader and journal-summarizer:

• Prevents context pollution in main conversation
• Uses Haiku model for efficiency
• Returns structured findings

Never read journals yourself - always delegate to agents.

Common Mistakes

After Starting

Once iteration is started:

• Journal file created with Beginning State and Intention
• Work normally on the goal using appropriate skills and workflows
• Track progress mentally or with TodoWrite
• Use /checkpoint-iteration to save progress before compaction or at interim points
• When ready to conclude, use /end-iteration to finalize journal entry