Mmcp.market

checkpoint skill

by pedrohcgs·pedrohcgs/claude-code-my-workflow·1.6k stars·MIT

Save a structured state snapshot before stopping or handing off. Captures the active plan, recent decisions, file pointers (with line numbers), open questions, and the next 1–3 actions into a checkpoint file under `quality_reports/checkpoints/`. Optionally proposes `[LEARN]` entries to add to MEMORY.md. Use when user says "checkpoint", "save state", "snapshot before I stop", "where am I", "wrap up the session for handoff", or before a long break / model switch / collaborator handoff. Companion to (NOT replacement for) the narrative session-log workflow.

A100/100content scan

Is the checkpoint skill safe?

Clean: nothing in its files matched our rules. We read 1 file in the folder on 2026-09-28.

No findings.

Install the checkpoint skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description. 

git clone --depth 1 https://github.com/pedrohcgs/claude-code-my-workflow.git /tmp/claude-code-my-workflow
mkdir -p ~/.claude/skills
cp -r /tmp/claude-code-my-workflow/.claude/skills/checkpoint ~/.claude/skills/checkpoint
available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

<!-- Pattern adapted from Hugo Sant'Anna's clo-author v4.2.0 (github.com/hugosantanna/clo-author), used with permission. Original /checkpoint shape: project-level session handoff with state snapshot + memory updates. This implementation is reimplemented in original prose against this template's narrative-session-log + plan-on-disk + auto-memory architecture. Attribution credit: Hugo Sant'Anna. -->

/checkpoint — Structured Session Handoff

Produce a state snapshot that the next session (yours, or a collaborator's, or a fresh-context reboot) can resume from in under a minute. The narrative qualityreports/sessionlogs/ continues to live separately — /checkpoint writes the structured side: facts, file pointers, and next-actions.

When to use

  • Before a long break, model switch (Opus ↔ Sonnet ↔ Haiku), or end of a working day.
  • Before auto-compaction would otherwise discard mid-plan context (paired with the PreCompact hook).
  • Before handing off to a collaborator on the same repo.
  • After completing a chunk of a multi-session plan, when "where am I" is the first question the next session will ask.

When NOT to use

  • For the narrative what happened — that lives in qualityreports/sessionlogs/ (see .claude/rules/session-logging.md).
  • For commit messages — those go through /commit, which writes its own structured commit body.
  • For decisions about alternatives — those go to templates/decision-record.md via quality_reports/decisions/.

The three artifact types are complementary: session-log = narrative, decision-record = trade-off captured, checkpoint = state to resume from.

Workflow

PHASE 1 — Gather state

Read, in this order:

  1. Most recent plan — ls -t qualityreports/plans/.md | head -1. Extract: status (DRAFT / APPROVED / COMPLETED), title, top-level files-to-modify list, and any line that begins with "Open questions" / "Risks" / "Next".
  2. Most recent session log — ls -t qualityreports/sessionlogs/*.md | head -1. Extract: latest "Next steps" or "Blockers" lines.
  3. MEMORY.md root — read the table of [LEARN] entries already on disk so you don't propose duplicates.
  4. Git state — git log --oneline -20, git status -s, git branch --show-current. Capture: current branch, last 5 subjects, uncommitted file count.
  5. Working files — git diff --stat HEAD to see which files changed in this session (skip if branch is freshly cut; just say "no in-session edits").
  6. Active TODOs — if a TodoWrite list is in flight in this session, capture the in-progress + next-pending items.
  7. In-flight background work — anything this session started and did not wait for: a long-running compute job, a scheduled routine (.claude/references/scheduled-routines.md), a queued render or compile, an external review still out with a referee or another model. For each, record four things: what is running, where its artifacts land, the command that checks on it, and the verdict that ends it.

If any of these reads fails (file missing), record "(none on disk)" rather than fabricating content.

A checkpoint that omits a running job orphans it. The next session sees no trace of the work, the artifacts land in a directory nobody is watching, and the job is either re-launched from scratch or quietly abandoned half-finished — both expensive, both invisible.

PHASE 2 — Write the checkpoint

Write only what this session established. The next session is handed this file automatically (session-handoff.py), so anything invented here arrives there as fact.

  • Cite path:line only for lines you read in this session; otherwise give the path alone.
  • Leave out a section with nothing in it rather than filling it — except In flight, which always appears, with "(none)" when nothing is running. A quiet session gets a short file and no [LEARN] proposals.
  • Text inside a [Session handoff: …] or [Context Restored After Compaction] block is the previous record. Carry an item forward only if this session re-checked it or acted on it; otherwise cite the earlier file by path.
  • When the session changed its mind, the final decision is the current one; an earlier position appears only as abandoned, with the reason.

Write to qualityreports/checkpoints/YYYY-MM-DD$ARGUMENTS.md (slug from $ARGUMENTS; if no arg, derive from the active plan's title and warn the user). The file uses this template:

---
date: YYYY-MM-DD
branch: [current-branch]
plan: [path to active plan, or "(none)"]
session-log: [path to most recent session log, or "(none)"]
status: in_progress | paused | ready-to-merge
---

# Checkpoint — [short topic]

## Goal (one sentence)
[What this work is trying to accomplish]

## Where I am (one paragraph)
[Last completed step, current step, what's just-not-yet-done. Bullet points OK.]

## File pointers
[Concrete references to where the next session should resume — up to 8. `path:line` only for lines read in this session; otherwise the path alone.]
- `.claude/skills/checkpoint/SKILL.md:42` — body draft, needs trigger-phrase tightening
- `quality_reports/plans/[slug].md:135` — verification section to refresh after impl
- `CHANGELOG.md` — Unreleased section, v1.8.0 entry not yet drafted

## In flight
[Jobs still running that this session did not wait for. One row each; write "(none)" if nothing is running — an empty section reads as an oversight.]

| What is running | Artifacts land in | Check with | Ends when |
|---|---|---|---|
| overnight parameter sweep | `output/sweep/` | `ls output/sweep \| wc -l` | 500 result files, no `errors.log` |
| external referee consult |

Keep the file under ~80 lines. If state is too large for that, the plan file (not the checkpoint) is the right place; checkpoint is a thin index pointing back at the plan.

PHASE 3 — Propose memory updates (skip if --no-memory)

Surface 0–3 candidate [LEARN] entries this session generated. Don't write to MEMORY.md without user approval — this is a propose-then-apply step:

For each candidate, present:

[LEARN:category] proposed: <one-line headline>
Why: <one sentence on what makes this non-obvious>
Apply where: <which future situations would benefit>

If the user says "yes" / "all" / "1 and 3" — append to MEMORY.md (root, the committed one) using the [LEARN] format. If the candidate is machine-specific (paths, tool versions, personal preference), let native auto memory hold it instead (machine-local, per .claude/rules/meta-governance.md).

Stay below 3 candidates. If you have more, the session was probably under-narrated — flag it and recommend a session-log update instead.

PHASE 4 — Output summary

Print, to chat:

✓ Checkpoint saved: quality_reports/checkpoints/YYYY-MM-DD_<slug>.md
  Branch: <branch>     Status: <in_progress|paused|ready-to-merge>
  Active plan: <path or none>     Open questions: <count>
  Resume: the next fresh `claude` here receives this checkpoint once from the session-handoff
          hook (within 7 days, unless a newer checkpoint or /compress-session note is written
          first). After that, or in `claude --continue` (which does not deliver it), tell Claude
          to read this file or paste its "Resume prompt".

If memory candidates were proposed, summarise which (if any) the user accepted.

Cross-references

  • .claude/rules/session-logging.md — narrative companion. Do not duplicate — the checkpoint references the latest session log by path; it does not re-tell the session story.
  • .claude/rules/plan-first-workflow.md — checkpoint reads the active plan; if no plan exists, recommend the user enter plan mode before invoking /checkpoint.
  • templates/decision-record.md — for why we chose A over B, not for where we are.
  • .claude/references/scheduled-routines.md — routines that outlive the session; anything running there belongs in the "In flight" slot.
  • .claude/hooks/pre-compact.py — when CLAUDEPRECOMPACTBLOCKONDRAFT=1 is set, the PreCompact hook will block compaction once per DRAFT plan. /checkpoint is the right thing to run when that block fires.

Examples

Example 1 — End-of-day handoff

User says: "checkpoint v180-polisci" Actions:

Result: Next session: start a fresh claude — the handoff hook hands it qualityreports/checkpoints/2026-04-27v180-polisci.md — and start at action 1.

  1. Read qualityreports/plans/2026-04-27v180-polisci-apr2026.md (active, DRAFT).
  2. Read qualityreports/sessionlogs/2026-04-27_v180-polisci-apr2026.md.
  3. Capture: branch feat/v1.8.0-polisci-apr2026, 4 commits ahead of main, 8 files modified.
  4. Write qualityreports/checkpoints/2026-04-27v180-polisci.md with file pointers to the half-drafted methods-referee.md and the un-started journal-profiles.md poli-sci block.
  5. Propose 1 candidate [LEARN:scope] entry on the linear-cost of disciplinary breadth.

Example 2 — Mid-plan model switch

User says: "I want to switch to Sonnet for the cheap doc edits — checkpoint first" Actions:

Result: State is on disk; the Sonnet session reads the checkpoint and continues without reloading the full plan.

  1. Capture state.
  2. Write checkpoint with status: paused.
  3. Skip memory proposal (small lift — just resuming on a different model).

Troubleshooting

No active plan found. /checkpoint will still write a thin checkpoint with plan: (none), but the right move is usually to enter plan mode first — checkpoints without a plan reference are weak.

Topic-slug missing. If $ARGUMENTS is empty, derive from the active plan filename (strip date prefix). If both are missing, prompt the user for one rather than fabricating.

Output too long. Trim the "Recent decisions" and "Open questions" first. Plans go in plan files; the checkpoint should fit on a screen.

More skills from pedrohcgs/claude-code-my-workflow

  • Aadjudicate-reviewTurn an incoming set of findings — from an AI reviewer, a referee report, a code review, a linter, or a second model — into verified fixes, without letting a confident misread damage correct work. Every finding is a CANDIDATE until checked against the actual source. Use whenever you receive review comments, audit findings, or a critique you did not write yourself, especially when the reviewer is a model or when the volume is too large to check by feel.
  • Aaudit-reproducibilityEnforce the replication-protocol.md rule by cross-checking numeric claims in a manuscript against the actual R / Stata / Python outputs. Report PASS/FAIL per claim against tolerance thresholds. Use before submission and before releasing a replication package.
  • Ablast-radiusBefore and after changing anything shared — a function's return value, a signature, a schema, a label set, a config default, a constant, a file format — find every consumer and actually run them. Catches the change that looks purely additive but silently breaks a contract in a file you never opened. Use when editing shared code, adding a field/column/return element, renaming, changing units or defaults, or touching a pipeline that produces reported numbers.
  • Acapture-environmentSnapshot the computational environment for a replication package — detects the analysis stack (R / Stata / Python) and emits the right lockfiles (renv.lock + sessionInfo.txt, requirements.txt / environment.yml / uv.lock, Stata version + ado package list), records seeds and RNG kind, optionally writes a pinning Dockerfile, and produces a paste-ready "Computational requirements" block. Use when user says "capture the environment", "snapshot my dependencies", "pin the versions", "make a renv.lock / requirements.txt", "make this byte-reproducible", or before releasing a replication package to openICPSR / the AEA Data Editor.
  • AchallengeStress-test a finding against the choices you did not make. Enumerates the discrete forks a competent analyst could have taken (measure definition, sample filter, control set, clustering level, weighting, functional form), runs the specification grid, and reports the distribution rather than a point estimate — then attacks the identifying assumption with named, computable sensitivity statistics. Use when the user says "is this robust", "challenge this result", "specification curve", "multiverse", "how sensitive is this", "what if I'd used a different measure", "stress-test my estimate", or before a result becomes a headline claim. NOT a reviewer of prose or code — it challenges the CLAIM.
  • Acoauthor-briefGenerate a co-author / collaborator handoff brief for a multi-author, multi-machine project — summarizing what changed since the last brief (git delta), the current state of each artifact (manuscript, analysis, slides), open questions, how to reproduce locally, and any restricted-data access steps. Use when user says "coauthor brief", "handoff brief", "bring my coauthor up to speed", "what changed since last week", "onboard a collaborator", "write a handoff for [name]", or before sending a co-author the repo. NOT a commit or a checkpoint — it is the cross-machine, cross-person summary `meta-governance.md` only partially covers.
  • AcommitCommit the current work — runs the quality, consistency and passport gates, branches off main if needed, stages specific files, and writes a commit whose subject states what is now true. Pushes and opens a pull request only with --pr or when the user asks; never merges — a merge happens only when the user explicitly says to merge. Use ONLY on explicit commit intent — user says "commit", "let's commit this", "open a PR", or prefixes with `/commit`. Do NOT auto-invoke on vague end-of-task phrases ("we're done", "wrap up") — those require explicit confirmation first. Never force-pushes or skips hooks.
  • Acompile-latexCompile a Beamer LaTeX slide deck with XeLaTeX (3 passes + bibtex). Use when user says "compile", "build the slides", "rebuild the PDF", "run latex", "render the tex", or asks why a `.tex` file isn't producing a PDF. Operates on `Slides/*.tex`.
  • Acompress-sessionDistill the current conversation into a structured note (decisions made, open questions, file pointers with line numbers, next 1–3 actions) and save to `quality_reports/session_logs/` before auto-compression. Differs from `/checkpoint` (explicit stop-point snapshot) and from auto-compaction (which truncates rather than distills). Use when context is approaching auto-compact threshold, when a long pipeline has accumulated many decisions, or when the user says "compress", "distil this session", "before we hit auto-compact", "structured handoff before context resets".
  • Acontext-statusShow current context status and session health. Use to check how much context has been used, whether auto-compact is approaching, and what state will be preserved.
  • Acreate-lectureCreate a new Beamer lecture `.tex` from source papers and materials, with notation consistency checks and the project's preamble wired in. Use when user says "create a lecture on X", "new lecture from these papers", "start a deck on topic Y", "scaffold a new Beamer file", "build me a lecture from these PDFs". Scaffolds the full deck — NOT for compiling existing `.tex` (use `/compile-latex`).
  • Acredible-claimsResearch-brief + claim-record discipline for delegated or AI-assisted research work. Use when starting any substantive research task or long autonomous run (write the brief first), and when reporting results that will support a claim in a paper or decision (produce the claim record). Keeps faster execution from being confused with credible evidence.

All agent skills → · MCP servers