| name | checkpoint |
| description | Save a structured state snapshot the next session can resume from — active plan, decisions and why, file pointers with line numbers, open questions, next 1-3 actions, and what to deliberately forget. Use before a break, a model switch, a collaborator handoff, or when context is approaching auto-compaction. Use when the user says "checkpoint", "save state", "where am I", "compress", "distil this session", "wrap up for handoff", "before we hit auto-compact". |
| author | geobr |
| version | 2.0.0 |
| argument-hint | [short-topic-slug] [--no-memory] |
| disable-model-invocation | true |
| allowed-tools | ["Read","Write","Glob","Grep","Bash"] |
/checkpoint — distil state, don't truncate it
Auto-compaction is lossy: it keeps recent turns and drops earlier ones, preserving no record of
what was decided. This skill writes the structured alternative — a file the next session (yours, a
fresh context, or a collaborator) can resume from in under a minute.
The narrative quality_reports/session_logs/ stays separate: session log = what happened,
checkpoint = state to resume from. The checkpoint links to the log; it does not re-tell it.
When to use
- Before a break, a model switch, or the end of a working day.
- When context is approaching auto-compaction and mid-session decisions would otherwise be lost.
- Before handing the repo to a collaborator.
- After a long debugging detour, so the dead ends are recorded as dead ends rather than carried
forward as live hypotheses.
Not for the narrative (that is the session log), for commit messages (/commit writes its own),
or for resetting context (/clear).
Phase 1 — Gather state
Read in this order; if something is missing, record (none on disk) rather than inventing it:
ls -t quality_reports/plans/*.md | head -1
ls -t quality_reports/session_logs/*.md | head -1
git branch --show-current; git log --oneline -10; git status -s; git diff --stat HEAD
Also read MEMORY.md so Phase 3 does not propose a duplicate, and capture any in-flight TodoWrite
items.
Phase 2 — Write the checkpoint
Write to quality_reports/checkpoints/YYYY-MM-DD_<slug>.md. Derive the slug from $ARGUMENTS, or
from the active plan's title if absent (say which you used). Keep it under ~80 lines — if state
does not fit, the plan file is the right home and the checkpoint should point at it.
---
date: YYYY-MM-DD
branch: <branch>
plan: <path to active plan, or (none)>
session-log: <path to latest log, or (none)>
status: in_progress | paused | ready-to-merge
why-now: break | model-switch | handoff | approaching-compaction | accumulated-noise
---
# Checkpoint — <topic>
## Goal
<one sentence: what this work is trying to accomplish>
## Where I am
<one short paragraph or a few bullets: last completed step, current step, what is not yet done>
## State
- **Last commit:** <sha + subject>
- **Working tree:** <clean | >
-
## File pointers
<3-8 concrete `path:line` references where the next session resumes>
- `r-package/R/utils.R:349` — download_parquet, failure branch under review
<2-5 bullets of reasoning that would NOT be obvious from the diff. Skip if none; do not pad.>
Phase 3 — Propose memory updates (skip with --no-memory)
Surface 0-3 candidate [LEARN] entries. Propose; never write to MEMORY.md unappproved:
[LEARN:category] <one-line headline>
Why: <what makes this non-obvious>
Apply where: <the future situation it changes>
On approval, append to MEMORY.md in the existing format. More than three candidates usually means
the session log is behind — say so instead of padding the list.
Phase 4 — Report
✓ Checkpoint: quality_reports/checkpoints/YYYY-MM-DD_<slug>.md
Branch: <branch> Status: <status> Why now: <why-now>
Plan: <path or none> Open questions: <n> Discarded: <n>
Resume: claude --continue, then read the checkpoint and start at action 1.
Anti-patterns
- Do not copy the conversation in. Distillation is the whole point.
- Do not let "Discarded as noise" recur. The same dead end across three checkpoints is a
structural problem — fix the docs or the workflow instead of re-discarding it.
- Do not write a checkpoint with no plan and no pointers. That is a note, not a resumable state;
enter plan mode first.
Cross-references
