checkpointing-an-iteration

Checkpointing an Iteration

Overview

Save current iteration progress by updating the journal entry with work performed so far, preserving state before potential context loss.

Core principle: Protect important context from compaction. Update journal incrementally during long conversations.

When to Use

Use this skill when:

• User runs /checkpoint-iteration command
• Conversation is getting long, compaction may be imminent
• Reached natural pause point mid-iteration
• Discovered important context that must be preserved
• Want to save progress before taking risky action

DO NOT use for:

• Ending the iteration (use ending-an-iteration instead)
• Starting iteration (use starting-an-iteration instead)

Quick Reference

Step	Action	Tool
1. Find journal file	Locate current iteration journal	Glob
2. Review conversation	Extract work performed so far	Manual review
3. Read current journal	Get existing content	Read
4. Update Work Performed	Append new findings	Edit
5. Announce checkpoint	Confirm save	Direct output

Process

Step 1: Find Journal File

Locate the current iteration's journal:

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

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

If no journal file found:

"No active iteration journal found.

This usually means `/start-iteration` wasn't run yet. Start an iteration first before checkpointing."

Stop here.

If journal file found: Extract the full path and proceed.

Step 2: Review Conversation

Review the conversation since iteration started to extract:

Skills & Workflows Used (so far):

• Scan for <invoke name="Skill"> tool calls
• Note which skills used and for what purpose

Key Decisions Made (so far):

• Identify major choices and rationale
• Note alternatives considered

Artifacts Created/Modified (so far):

• Files created or changed
• Git commits made
• Pull requests opened

External Context Gathered (so far):

• Web research findings
• User feedback
• Documentation consulted

Reasoning & Strategy Changes (so far):

• Why certain approaches chosen
• Where strategy pivoted

Blockers Encountered (so far):

• What's preventing progress
• Dependencies identified

Open Questions (so far):

• What needs resolution
• Decisions deferred

Step 3: Read Current Journal

Read the existing journal file to see what's already documented:

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

The journal will have:

• Metadata header (# Iteration NNNN - YYYY-MM-DD)
• Beginning State section (from starting-an-iteration)
• Iteration Intention section (from starting-an-iteration)
• Work Performed section (may be partially filled from previous checkpoint, or empty)
• Ending State section (will be empty - that's for ending-an-iteration)
• Iteration Metadata section (will be empty - that's for ending-an-iteration)

Step 4: Update Work Performed Section

Update the "Work Performed" section with current findings from Step 2.

If Work Performed section is empty: Replace the empty section with full content:

## Work Performed

### Skills & Workflows Used
[From Step 2 review]

### Key Decisions Made
[From Step 2 review]

### Artifacts Created/Modified
[From Step 2 review]

### External Context Gathered
[From Step 2 review]

### Reasoning & Strategy Changes
[From Step 2 review]

### Blockers Encountered
[From Step 2 review]

### Open Questions
[From Step 2 review]

If Work Performed section already has content: Merge new findings with existing:

• Add new skills to "Skills & Workflows Used" list
• Add new decisions to "Key Decisions Made"
• Add new artifacts to "Artifacts Created/Modified"
• Append new findings to other sections
• Preserve all existing content

Use Edit tool to update the file.

Step 5: Announce Checkpoint

Report to user:

**Checkpoint saved for iteration [N]**

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

## Checkpoint Summary
- **Skills used:** [Count] skills/workflows
- **Decisions made:** [Count] key decisions
- **Artifacts created:** [Count] files/commits
- **Blockers:** [Count] blockers identified
- **Open questions:** [Count] questions pending

Context preserved. Safe to continue or compact conversation.

---

To finalize this iteration, use `/end-iteration` when ready.

Important Notes

Checkpoint vs. End Iteration

Checkpoint:

• Updates journal mid-iteration
• Iteration continues after checkpoint
• Can checkpoint multiple times per iteration
• Doesn't update summary.md
• Doesn't finalize "Ending State"

End Iteration:

• Finalizes journal entry
• Iteration concludes
• Writes final "Ending State"
• Updates summary.md if needed (every 5 iterations)
• Conversation ends or new iteration starts

Multiple Checkpoints

It's fine to checkpoint multiple times:

• Each checkpoint merges with previous content
• Later checkpoints add to earlier ones
• All information accumulated in journal

What Gets Preserved

Checkpointing preserves:

• Work done so far
• Decisions and reasoning
• Blockers discovered
• Context gathered

Checkpointing does NOT capture:

• Future plans (that's in "Ending State" at iteration end)
• Final assessment (that's for ending-an-iteration)
• Complete iteration story (still in progress)

Merging Strategy

When updating Work Performed with existing content:

• Append new items to lists (don't overwrite)
• Preserve all existing information
• Deduplicate if same item mentioned twice
• Maintain chronological order within sections

Common Mistakes

Mistake	Reality
"I'll create new journal file for checkpoint"	NO. Update existing journal from starting-an-iteration.
"I'll overwrite existing Work Performed section"	NO. Merge new content with existing.
"I'll write Ending State during checkpoint"	NO. That's only for ending-an-iteration.
"Checkpoint means iteration is over"	NO. Iteration continues after checkpoint.
"I'll skip checkpoint if conversation isn't long"	NO. Checkpoint anytime user requests it.

After Checkpointing

Once checkpoint is saved:

• Journal updated with current progress
• Context preserved against compaction
• Iteration continues normally
• Can checkpoint again later if needed
• When ready to conclude, use /end-iteration