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