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

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

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