start-iteration

name	start-iteration
description	Use when beginning a new conversation to work on an open-ended goal, loading context from previous iterations through iteration journals
user-invocable	true

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

Step	Action	Tool/Agent
1. Detect goal	Check for autonomy directory	Glob
2. Load recent context	Read last 3-5 iterations	Task (journal-reader)
3. Load older context	Read summary.md if >5 iterations (read-only — do NOT update)	Read
4. Present state	Show context to user	Direct output
5. Create journal	Write initial journal entry	Write
6. Ready to work	Create TodoWrite tracker	TodoWrite

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.

Rationalization at iteration start	Reality
"Summary looks outdated, I'll refresh it"	NO. Wait for the next iteration-end milestone.
"There's no summary yet, I'll create one"	NO. It will be created at the end of iteration 5/10/15/etc.
"I'll just have the agent regenerate it real quick"	NO. Read-only at iteration start.

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

Mistake	Reality
"I'll quickly read the journals myself"	NO. Always dispatch agents. Journals can be large.
"User goal seems closed-ended, but I'll use autonomy anyway"	NO. Autonomy is for open-ended goals only.
"I'll skip loading older iterations to save time"	NO. Context is critical. Always load per strategy.
"I'll create summary.md myself"	NO. summary.md is owned by end-iteration and only updated at the end of every 5th iteration.
"summary.md is missing/stale, I'll refresh it now"	NO. At iteration start it is read-only. Wait for the next end-of-iteration milestone (5, 10, 15, …).
"I'll dispatch journal-summarizer at the start"	NO. Never dispatch journal-summarizer from start-iteration. It is only dispatched by end-iteration on milestone iterations.
"Goal exists, so I'll skip asking user what to work on"	NO. Always present state and ask for direction.

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