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:

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).
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)
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

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

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?]

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:

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
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"
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
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

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>

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

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
)"

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"

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

ending-an-iteration

Ending an Iteration

Overview

When to Use

Quick Reference

Process

Step 1: Review Conversation

Step 2: Identify Stopping Point

Step 3: Complete Journal Entry

Step 4: Update Summary (if needed)

Step 5a: Git Commit and Tag

Step 5b: Announce Completion

Important Notes

Journal File Already Exists

Merging with Checkpoint Content

Comprehensive Documentation

Date in Filename

Don't Skip Sections

Git Integration

Common Mistakes

After Ending