checkpoint

Checkpoint Skill

Save current task progress to a structured YAML checkpoint file that survives context loss.

When to Use

• Session ending: Before closing session or switching tasks
• Context window full: Approaching token limit
• Significant progress: Completed a major phase or experiment
• Before risky operations: Before destructive changes or complex merges
• Manual checkpoint: User explicitly requests /checkpoint

Step 1 — Gather current state

Review conversation history and files to extract:

Phase tracking:

• What phase are we in? (e.g., parameter_extraction, mesh_generation, convergence_testing, debugging, implementation)
• What phases are completed?
• What phases are next?

Critical state:

• Parameters: Extracted values with sources (paper page/table or "estimated from X") and confidence levels
• Experiments: What's been tried? Status (pending/in_progress/completed/failed/diverged), results paths, failure reasons
• Decisions: Key choices made, rationale, alternatives considered
• Custom state: Task-specific data (meshes, models, datasets, API endpoints, etc.)

Blockers:

• Open questions blocking progress
• Decisions needed
• Assumptions made that need verification

Artifacts: Critical files (configs, results, scripts) with roles

Resume instructions: Specific commands to run next session, conditions to verify

Step 2 — Determine checkpoint filename

BRANCH=$(git branch --show-current)
TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
CHECKPOINT_FILE=".claude/checkpoints/${BRANCH}-${TIMESTAMP}.yaml"
mkdir -p .claude/checkpoints

Step 3 — Write checkpoint YAML

Quality bar:

• Every parameter must have source (paper page/table or "estimated from X")
• Every failed experiment must have reason (not just "didn't work")
• Every decision must have rationale
• Resume instructions must be actionable (specific commands or file checks, not vague "continue work")

Example checkpoint: