shield_lock
JinDaGe
← Back to skills
extension
Category: AI Agent CapabilitiesNo API key required

checkpointing-an-iteration

Use when saving current iteration progress mid-conversation, before context compaction, or at interim pause points

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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