# Start Iteration

> Use when beginning a new conversation to work on an open-ended goal, loading context from previous iterations through iteration journals

- Skill: `tilmon-engineering/start-iteration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tilmon-engineering/start-iteration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tilmon-engineering/start-iteration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tilmon-engineering (https://skillmd.com/u/tilmon-engineering)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tilmon-engineering/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](https://github.com/ed3dai/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:

```bash
# 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:**
   ```bash
   # 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):

```markdown
**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:**

```markdown
# 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