Ending An Iteration

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

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

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