checkpoint

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"