Ending an Iteration

Overview

Conclude the current iteration by reviewing the conversation, documenting what happened, and preparing state for the next iteration.

Core principle: Comprehensive journaling enables continuity. Future iterations depend on accurate state capture.

When to Use

Use this skill when:

• User runs

  /end-iteration

  command
• Agent suggests natural stopping point and user confirms
• Context limit approaching and good time to pause
• Subtask complete and ready to hand off to next iteration

DO NOT use for:

• Middle of active work (finish current subtask first)
• Before resolving critical blockers (unless blocked externally)

Quick Reference

Step	Action	Tool
1. Review conversation	Extract skills, decisions, artifacts	Manual review
2. Identify stopping point	Why is this iteration ending?	User confirmation
3. Complete journal entry	Update existing journal file	Read, Edit
4. Update summary	If iteration 5, 10, 15, etc.	Task (journal-summarizer)
5a. Git commit and tag	Commit journal to current branch	Bash
5b. Announce completion	Confirm next steps	Direct output

Process

Step 1: Review Conversation

Review the full conversation to extract key information:

Skills & Workflows Used:

• Scan conversation for

  <invoke name="Skill">

  tool calls
• Note which skills were used and for what purpose
• Generic detection - works with any plugin skills

Example findings:

### Skills & Workflows Used
- `brainstorming`: Designed pricing tier alternatives
- `hypothesis-testing`: Validated annual billing preference
- `internet-researcher`: Found competitor pricing data

Key Decisions Made:

• Identify major choices: architecture, strategy, approach
• Note rationale: why was this chosen?
• Record alternatives considered

Example:

### Key Decisions Made
- **Decision:** Implement usage-based pricing tier
  **Rationale:** Research showed power users want to scale gradually
  **Alternatives:** Flat enterprise tier (rejected: less flexible)

Artifacts Created/Modified:

• Files created or changed (use git status/diff if applicable)
• Git commits made during iteration
• Pull requests opened
• Documentation written

Example:

### Artifacts Created/Modified
- `src/pricing/usage-tier.ts`: New usage-based pricing calculator
- `docs/pricing-strategy.md`: Documented pricing decision rationale
- Git commit: abc123f "Add usage-based pricing tier"

External Context Gathered:

• Web research findings
• User feedback received
• Documentation consulted
• Competitor analysis

Example:

### External Context Gathered
- Research: Competitor X charges $0.10/unit, Competitor Y charges $0.15/unit
- User feedback: "Annual discount of 20% drives conversions"
- Documentation: Stripe API supports usage-based billing natively

Reasoning & Strategy Changes:

• Why certain approaches were chosen
• What alternatives were explored
• Where strategy pivoted and why

Example:

### Reasoning & Strategy Changes
- Initially planned flat enterprise tier
- Research showed power users prefer scaling gradually
- Pivoted to usage-based model to reduce friction
- This aligns with SaaS best practices for 2026

Blockers Encountered:

• What's preventing progress?
• Dependencies on external factors
• Questions needing answers

Example:

### Blockers Encountered
- Stripe webhook integration unclear: need to consult API docs
- Finance team needs to approve pricing before launch
- Usage tracking infrastructure not yet built (dependency)

Open Questions:

• What needs to be resolved next?
• Decisions deferred to future iterations
• Unknowns requiring investigation

Example:

### Open Questions
- Should we offer annual discount on usage-based tier?
- What's the right per-unit price point?
- Do we need a minimum monthly commit?

Step 2: Identify Stopping Point

Determine why this iteration is ending:

Ask user to confirm:

"Suggested stopping point: [reason]. Should we end this iteration?"

Reasons:
- Subtask complete: [what was finished]
- Blocked on: [external dependency]
- Context approaching limit
- Natural break point: [why this makes sense]

User confirms → Proceed to write journal

User wants to continue → Return to work, don't end iteration yet

Step 3: Complete Journal Entry

The journal file was created by starting-an-iteration. Now complete it:

1. Find current journal file:

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

   Sort by iteration number and identify the most recent (should be today's date).

2. Read existing journal:

   # Use Read to load current content
   file: "autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md"
   

   Journal will have:

   • Beginning State (from starting-an-iteration)
   • Iteration Intention (from starting-an-iteration)
   • Work Performed (may be filled by checkpointing, or still empty)
   • Ending State (empty - we'll fill this)
   • Iteration Metadata (empty - we'll fill this)

3. Update Work Performed section:

   Using findings from Step 1, update the Work Performed subsections.

   If Work Performed is empty: Replace entire section with Step 1 findings.

   If Work Performed has content (from checkpointing): Merge Step 1 findings with existing:

   • Add any new skills/workflows used since checkpoint
   • Add any new decisions made since checkpoint
   • Add new artifacts created since checkpoint
   • Append new context gathered since checkpoint
   • Note any additional blockers or questions
   • Preserve all existing checkpoint content

4. Fill Ending State section:

   ## Ending State
   [What is the state NOW at iteration end?]
   - Progress made during this iteration
   - What's complete vs. what remains
   - Updated metrics (if applicable)
   - How well did we achieve the iteration intention?
   - Recommended next steps for iteration N+1
   

5. Fill Iteration Metadata section:

   ## Iteration Metadata
   - Context usage: [Note if approaching limits, if compaction occurred]
   - Checkpoints: [How many times was checkpoint-iteration used?]
   - Suggested next action: [What should iteration N+1 work on?]
   

6. Update file using Edit tool:

   • Replace Work Performed section (merge with existing)
   • Replace Ending State section (fill in)
   • Replace Iteration Metadata section (fill in)
   • Preserve Beginning State and Iteration Intention sections

Step 4: Update Summary (if needed)

Check if summary update is needed:

Update summary every 5 iterations: 5, 10, 15, 20, etc.

If current iteration number % 5 == 0:
   Dispatch journal-summarizer agent to update summary.md

Dispatch journal-summarizer:

Task tool with subagent_type: "autonomy:journal-summarizer"
Prompt: "Update summary.md for goal '[goal-name]' to include iterations 1-[N].
        Previous summary covered iterations 1-[N-5].
        Add new learnings, update metrics, note new blockers."
Model: haiku

Wait for agent to update summary.md

Step 5a: Git Commit and Tag

After journal is complete and summary is updated (if needed), commit to git:

1. Extract iteration metadata:

   • Goal name from journal path:

     autonomy/[goal-name]/

   • Iteration number from filename:

     iteration-NNNN-YYYY-MM-DD.md

   • Extract 2-3 line summary from Ending State section

2. Determine iteration status:

   Analyze Ending State section to determine status:

   • Look for explicit status indicators: "This is a dead end", "Approach invalidated", "Successfully completed", "Blocked by", etc.
   • active (default) - Normal progression, work continuing
   • blocked - Contains phrases like "blocked by", "waiting on", "cannot proceed until"
   • concluded - Contains phrases like "successfully completed", "goal achieved", "experiment succeeded"
   • dead-end - Contains phrases like "dead end", "not working", "abandoning approach", "invalidated"

3. Extract quantitative metrics:

   Parse Ending State for metrics with numbers:

   • Look for patterns like "MRR: $62k (+12%)", "Build time: 3.2min (-40%)", "Churn: 8% (from 13%)"
   • Collect all quantitative progress indicators
   • Format as single line:

     Metrics: [metric1], [metric2], ...

     or "None" if no metrics

4. Summarize journal content:

   Create 4-6 sentence summary from Work Performed and Ending State:

   • What was accomplished this iteration
   • Key decisions made and rationale
   • Major learnings or discoveries
   • How this iteration moved toward the goal
   • Be substantive but concise - this is for git log readers

5. Build enhanced commit message:

   journal: [goal-name] iteration NNNN
   
   [2-3 line summary from Ending State - as before]
   
   ## Journal Summary
   
   [4-6 sentence summary from step 4 above - what happened, what was learned, what changed]
   
   ## Iteration Metadata
   
   Status: [active|blocked|concluded|dead-end]
   Metrics: [quantitative metrics from step 3, or "None"]
   Blockers: [summary from Blockers Encountered section, or "None"]
   Next: [next iteration intention from Iteration Metadata section]
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   
   Co-Authored-By: Claude <noreply@anthropic.com>
   

6. Stage files:

   # Always stage journal file
   git add autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md
   
   # If summary was updated this iteration (iteration % 5 == 0)
   git add autonomy/[goal-name]/summary.md
   

7. Create commit:

   # Use heredoc for multi-line message with enhanced format
   git commit -m "$(cat <<'EOF'
   journal: [goal-name] iteration NNNN
   
   [2-3 line summary from Ending State]
   
   ## Journal Summary
   
   [4-6 sentence summary of iteration]
   
   ## Iteration Metadata
   
   Status: [active|blocked|concluded|dead-end]
   Metrics: [metrics or "None"]
   Blockers: [blockers or "None"]
   Next: [next iteration intention]
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   
   Co-Authored-By: Claude <noreply@anthropic.com>
   EOF
   )"
   

8. Create annotated tag with branch-aware naming:

   # Get current branch name
   current_branch=$(git branch --show-current)
   
   # Extract strategy name from branch
   # For autonomy branches: "autonomy/experiment-a" → "experiment-a"
   # For non-autonomy branches: use goal name as strategy
   if [[ "$current_branch" =~ ^autonomy/ ]]; then
     strategy_name=${current_branch#autonomy/}
   else
     # Use goal name from journal path
     strategy_name="[goal-name]"
   fi
   
   # Tag format: autonomy/<strategy-name>/iteration-NNNN (4 digits, zero-padded)
   git tag -a "autonomy/${strategy_name}/iteration-$(printf '%04d' NNNN)" \
     -m "journal: [goal-name] iteration NNNN"
   

9. Handle errors gracefully:

   • If git operations fail (not a repo, detached HEAD, permissions, etc.):
     • Capture error message
     • Continue to Step 5b anyway (journal is written, that's critical)
     • Report warning to user with manual commands

Error reporting format:

⚠️ **Git Integration Warning:**
Failed to commit journal: [error message]

You can manually commit with:
  git add autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md
  git commit -m "journal: [goal-name] iteration NNNN ..."
  git tag -a "autonomy/[strategy-name]/iteration-NNNN" -m "journal: [goal-name] iteration NNNN"

Success indicator:

• If git operations succeed, note success for Step 5b announcement
• Tag

  autonomy/[strategy-name]/iteration-NNNN

  marks this iteration in git history

Step 5b: Announce Completion

Report to user with git status:

If git operations succeeded:

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

✓ Journal committed and tagged: `autonomy/[strategy-name]/iteration-NNNN`

Journal entry: `autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md`
Branch: [current-branch-name]
Status: [active|blocked|concluded|dead-end]

## Summary of This Iteration
- **Work completed:** [Brief summary]
- **Key decisions:** [Major choices made]
- **Blockers:** [What's preventing progress]
- **Next steps:** [Recommended for iteration N+1]

---

**Ready to resume in next conversation with `/start-iteration`**

If git operations failed:

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

Journal entry written: `autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md`

⚠️ **Git Integration Warning:**
Failed to commit journal: [error message]

You can manually commit with:
  git add autonomy/[goal-name]/iteration-NNNN-YYYY-MM-DD.md
  git commit -m "journal: [goal-name] iteration NNNN ..."
  git tag -a "autonomy/[strategy-name]/iteration-NNNN" -m "journal: [goal-name] iteration NNNN"

## Summary of This Iteration
- **Work completed:** [Brief summary]
- **Key decisions:** [Major choices made]
- **Blockers:** [What's preventing progress]
- **Next steps:** [Recommended for iteration N+1]

---

**Ready to resume in next conversation with `/start-iteration`**

Important Notes

Journal File Already Exists

The journal file was created by starting-an-iteration with:

• Beginning State (from context loading)
• Iteration Intention (from user input)
• Empty Work Performed sections (to be filled)

Your job is to complete the journal, not create it from scratch.

Merging with Checkpoint Content

If user ran

/checkpoint-iteration

during the iteration:

• Work Performed section will have partial content
• Merge your Step 1 findings with existing content
• Add new information discovered since checkpoint
• Don't overwrite or lose checkpoint data

Comprehensive Documentation

Critical: Future iterations depend entirely on this journal. Include:

• Enough detail that iteration N+1 can pick up seamlessly
• Rationale for decisions (not just what, but why)
• All blockers, even minor ones
• Specific next steps, not vague "continue working"

Date in Filename

Always use today's date (YYYY-MM-DD format):

# Get current date
date +%Y-%m-%d

Don't Skip Sections

Even if a section is empty, include it with a note:

### Blockers Encountered
None - iteration progressed smoothly

This shows the section was considered, not forgotten.

Git Integration

Automatic commits to current branch:

• Journal file is committed to whatever branch you're currently on
• Does NOT create new branch or switch branches
• Uses enhanced commit message format with:
  • Brief summary (2-3 lines)
  • Journal Summary section (4-6 sentences)
  • Iteration Metadata section (status, metrics, blockers, next steps)
• Tags commit as

  autonomy/<strategy-name>/iteration-NNNN

  for branch-aware navigation

Branch-aware tagging:

• On autonomy branches: Tag uses branch name (e.g.,

  autonomy/experiment-a/iteration-0015

  )
• On non-autonomy branches: Tag uses goal name (backward compatibility)
• Each branch has its own iteration namespace
• No tag collisions when multiple branches have same iteration number

Error handling:

• Git failures do NOT block iteration completion
• Journal is always written, even if commit fails
• User receives manual commands if git fails
• Graceful degradation ensures state is preserved

What gets committed:

• Always:

  iteration-NNNN-YYYY-MM-DD.md

  journal file
• Sometimes:

  summary.md

  (if iteration % 5 == 0)
• Never: Other files in working directory

Tag benefits:

• Navigate to iteration on specific branch:

  git checkout autonomy/experiment-a/iteration-0042

• List all iterations on a branch:

  git tag -l 'autonomy/experiment-a/*'

• List all autonomy iterations:

  git tag -l 'autonomy/*/*'

• Immutable history markers for CI/CD integration
• Enables branch management commands to query git log for metadata

Common Mistakes

Mistake	Reality
"I'll create new journal file instead of updating existing"	NO. Journal was created by starting-an-iteration. Update it with Edit tool.
"I'll overwrite Work Performed that has checkpoint content"	NO. Merge with existing. Preserve checkpoint data.
"Journal is too detailed, I'll abbreviate"	NO. Be comprehensive. Future iterations need full context.
"No blockers this time, I'll skip that section"	NO. Write "None" to show you checked.
"Summary update can wait"	NO. If iteration % 5 == 0, update summary.
"I'll skip comparing against iteration intention"	NO. Ending State should assess how well intention was achieved.
"Git commit failed, so iteration failed"	NO. Journal writing is critical, git commit is helpful. Warn about git error but complete iteration.
"I'll create a new branch for the commit"	NO. Commit to current branch. User controls branching strategy.

After Ending

Once iteration is ended:

• Journal file completed with Ending State and Iteration Metadata
• Summary updated if needed (every 5 iterations)
• Git commit created and tagged as

  autonomy/iteration-NNNN

  (if git operations succeeded)
• Full iteration story captured for next iteration
• Can start new iteration anytime with

  /start-iteration