checkpoint

name	checkpoint
description	Use when you need to save session state to survive context compaction or handoff between sessions.
allowed-tools	Read, Write, Edit, Bash(git*), Bash(date*), Bash(wc*), Glob

Checkpoint — Save Session State

Snapshot the current session's progress to a YAML file so it can be restored after context compaction or in a new session. This is NOT a session log (narrative) or context save (profile/focus) — it's a machine-readable state dump for continuity.

When to Use

• Before a session is likely to hit context compression (many tool calls, long outputs)
• At phase boundaries in multi-phase work
• When the user says "save state", "checkpoint", "save progress"
• Proactively when you sense context is getting large — don't wait to be asked

When This Skill Is Invoked

Step 1: Gather State

Collect the following from the current conversation context:

1. Project — which project directory are we working in?
2. Task — what was the user's original request this session?
3. Files modified — list every file you've created or edited this session (use git diff --name-only if in a git repo, plus any new untracked files)
4. Decisions made — key choices and their rationale (e.g., "chose LaTeX over Markdown because...", "used sonnet for cron jobs to reduce cost")
5. Current step — where in the plan are we? What just completed? What's next?
6. Blocked items — anything that couldn't be completed and why
7. Open questions — unresolved ambiguities that need user input

Step 2: Write Checkpoint

Write to .planning/checkpoint.yaml in the active project directory. If no project directory is obvious, write to the Task Management root.

# Auto-generated by checkpoint — do not edit manually
created: "YYYY-MM-DDTHH:MM:SS"
session_id: "<from $CLAUDE_SESSION_ID if available>"
project: "<project directory basename>"

task: |
  <one-paragraph description of what the user asked for>

files_modified:
  - path: "relative/path/to/file.md"
    action: "created|edited|deleted"
    summary: "what was changed and why"

decisions:
  - decision: "what was decided"
    rationale: "why"

progress:
  completed:
    - "step 1 description"
    - "step 2 description"
  current: "what step we're on now"
  next:
    - "next step 1"
    - "next step 2"

blocked:
  - item: "what's blocked"
    reason: "why"

open_questions:
  - "question that needs user input"

context_files:
  - "list of files that should be re-read on restore"

Step 3: Confirm

Report to the user:

Checkpoint saved to .planning/checkpoint.yaml
- N files modified
- N decisions recorded
- Current step: [description]
- Next: [first next step]

Schema Rules

• files_modified: Only files touched THIS session, not all project files
• decisions: Only non-obvious choices. Skip mechanical decisions ("used latexmk" is obvious; "chose TWFE over CS estimator" is not)
• context_files: List files that restore should re-read to reconstruct working context. Include CLAUDE.md, the plan file, and any files being actively edited
• progress.current: Must be specific enough that restore can pick up exactly where we left off
• Timestamps: Always ISO format, always local timezone

Multiple Checkpoints

Each checkpoint invocation overwrites the previous checkpoint. There is only one active checkpoint per project. If you need history, the git log preserves it.

Anti-Patterns

• Do NOT write narrative prose — this is structured data for machine consumption
• Do NOT include file contents — only paths and summaries
• Do NOT checkpoint trivially (single-file edits with no decisions) — it's overhead without value
• Do NOT use this instead of session-log — session logs are for humans, checkpoints are for restore