synthesis-checkpoint

name	synthesis-checkpoint
description	Mid-session refresh and drift-recovery protocol. Re-syncs the agent's awareness of current date, project state, and recent commit history when context may have drifted from disk. Use when asked to: checkpoint, re-sync, refresh context, mid-session refresh, recover from compaction, re-read project state, verify dates, drift check, where are we, what was last done, am I caught up. Invoke on any suspicion of context drift, after long conversation pauses, or before generating time-interval claims.
license	CC0-1.0
depends_on	[]
metadata	{"author":"Rajiv Pant","version":"1.0.0","source_repo":"github.com/synthesisengineering/synthesis-skills","source_type":"public"}

Synthesis Checkpoint — Mid-Session Refresh & Drift Recovery

The Problem

LLMs are stateless at the model level. Across a long conversation, an LLM's sense of "what's true now" can drift from what's actually on disk and in git. Drift sources:

• Time drift. The model has no clock. If the conversation started Tuesday and continues Wednesday, the model often still thinks it's Tuesday.
• State drift. Project CONTEXT.md may have been edited (by user, by sub-agent, by another session) since the model last read it.
• Compaction drift. When the context window approaches its limit, the harness may summarize older turns. Details disappear. The model often cannot detect that this happened.
• Cached-fact drift. Facts the model read earlier in the conversation (last commit, last session date, last decision) may no longer be true.

Self-discipline degrades with conversation length. Rules read at session start lose salience as turns accumulate. Even a model that "knows" to verify often skips verification under the weight of accumulated context.

This skill is the recovery primitive. It is a tight, low-friction protocol the agent runs on demand or on a detected drift signal — and the act of running it restores ground truth.

When To Invoke

Invoke synthesis-checkpoint when any of these conditions fire:

Triggered by the user:

• User asks "where are we?" / "what's the status?" / "what's been done?"
• User asks the agent to continue work after a pause
• User says "remember to..." or "you forgot..."
• User indicates the agent has drifted ("that's not right", "you said earlier...", "actually...")
• User invokes this skill by name or by keyword (checkpoint, re-sync, refresh)

Triggered by the agent's own self-monitoring:

• Before generating any time-interval claim ("N days ago", "yesterday", "last session", "this week")
• Before quoting any project status from cached memory
• After a noticeable gap in conversation (model can check date to compare against perceived time)
• After ~25 substantive tool calls, regardless of perceived need
• When the model says or thinks "I don't recall" about a recent decision
• When a file read reveals content the model didn't expect (state drift signal)
• When the user references a decision the model has no record of (compaction signal)
• When resuming work on a project after working on something else in the same session

Triggered automatically by hooks (Claude Code):

• SessionStart hook runs an equivalent of this skill's initial steps
• Stop hook detects long sessions and emits a re-sync reminder
• PreToolUse hook (for time-sensitive operations) injects current date

The Protocol

Steps run in order. Each step is one shell or file operation; total cost is ~5 tool calls.

Step 1 — Verify current time

date "+%Y-%m-%d %H:%M:%S %Z (%A)"

Read the output. Set this as your authoritative "current time" anchor. Compare to whatever you previously believed about the current time. Note any difference larger than a few minutes — that's drift, and it means in-context time impressions are unreliable.

Step 2 — Verify project state from disk

Identify the active project. Typically the one whose CONTEXT.md is in the current working directory or was most recently mentioned.

Read its files in this order:

1. CONTEXT.md — current state, what's next, recent sessions
2. The latest entry in sessions/YYYY-MM.md (whichever monthly file is most recent)
3. REFERENCE.md (full file or section-skim, depending on size)

Note the "Last session" header in CONTEXT.md. Do not trust it as authoritative — it is a cache. Treat it as a starting hypothesis to verify in Step 3.

Step 3 — Verify project history from git

git log -10 --pretty=format:"%h %ai %s" -- <project-path>

Read the most recent ~10 commit timestamps and subjects. This is the source of truth for "what happened when in this project."

Cross-check against CONTEXT.md's "Last session" claim:

• If CONTEXT.md's "Last session" date matches the most recent project-touching commit's date — proceed; the cache is fresh.
• If CONTEXT.md's "Last session" date is OLDER than the most recent commit — CONTEXT.md is stale; the most recent commit's date is the real "last session." Note the discrepancy.
• If CONTEXT.md's "Last session" date is NEWER than the most recent commit — uncommitted work exists OR the date in CONTEXT.md was written incorrectly. Run git status to disambiguate.

Step 4 — Cross-reference tasks and recent decisions

If the agent uses TaskCreate / TaskList for in-session tracking, run TaskList. Read the current state of pending and in_progress tasks. This is the third source of truth (in-session memory) to compare against disk + git.

If there's a planning artifact (a plan file, a design doc, a checklist) referenced from CONTEXT.md — re-read it.

Step 5 — Reconcile and report

In one short paragraph in the next response to the user, state:

• Today's verified date and time
• The project's verified "last session" date (from git log)
• Where the agent's mental state diverged from disk/git, if anywhere
• What the agent will do next, grounded in the verified facts

Show this verification step in the response. It is the L4 visible-verification mechanism from the synthesis-context-temporal-continuity project — the user must be able to see that the checkpoint ran and what it produced.

Step 6 — Update CONTEXT.md if it was stale

If Step 3 revealed CONTEXT.md was out of date (later commits exist that aren't reflected in its "Last session" or "Recent Sessions" sections), update CONTEXT.md in place to reflect verified facts. Commit and push that update separately from any other work. This prevents the next session from inheriting the stale cache.

Output Format

The agent's response after invoking this skill should include something like:

Checkpoint complete. Verified facts:

• Today: 2026-05-27 10:49 EDT (Wednesday)
• Last project commit: 2026-05-26 12:47 EDT (commit 51b8e6d, "Maintain context: refresh inbox-cleanup CONTEXT.md")
• Interval since last session: ~22 hours
• CONTEXT.md "Last session" matched git log — cache was fresh
• In-progress task: [task summary from TaskList]

Proceeding with [next action].

If discrepancies were found:

Checkpoint complete — drift detected. Verified facts:

• Today: 2026-05-27 10:49 EDT
• CONTEXT.md said: "Last session: 2026-05-18 (PM)"
• Git log said: most recent project commit is 2026-05-26 ("re-verification sweep")
• Interpretation: CONTEXT.md was mis-labeled; the May 26 sweep was the real last session.
• Action: updating CONTEXT.md with corrected dates before continuing.

What Counts as "Substantive Work"

Trigger the checkpoint protocol BEFORE these kinds of work, not after:

• Writing a session-log entry
• Computing or claiming a time interval ("X days ago", "yesterday", "this week")
• Quoting project status to the user
• Making a planning decision based on "where we left off"
• Generating a commit message that mentions dates or intervals

After-the-fact verification catches some errors but lets stale facts propagate into outputs first. Verifying first is cheaper than correcting later.

Relationship to Other Synthesis Skills

This skill is the recovery primitive that other skills delegate to:

• synthesis-context-lifecycle — references this skill in its Session Start Protocol and Mid-Session Refresh Protocol. The lifecycle skill defines the architecture of CONTEXT.md / REFERENCE.md / sessions/; this skill is the per-invocation drift-check.
• synthesis-daily-rituals — references this skill in its day-start ritual. Day-start always runs a checkpoint before any project work begins.
• synthesis-project-management — references this skill in its project-discovery protocol. When the user mentions a project, the agent runs a checkpoint on that project's files.

These skills are independent. Each works standalone. But they are stronger when they all delegate the drift-check to this single skill, which guarantees a consistent protocol.

Why This Works

The synthesis project management system already has the durable layer (CONTEXT.md, REFERENCE.md, sessions/, git history). The failure mode is not lack of data — it's the agent's in-context memory drifting from that data over time. This skill's only job is to force a re-sync against the durable layer at the moments when it matters most.

It is intentionally lightweight (~5 tool calls), intentionally codified (no variation between invocations), and intentionally visible (the user sees the verification step). All three properties matter:

• Lightweight — runs without the agent rationalizing "this isn't worth the steps"
• Codified — runs the same way every time, so users can recognize when it ran and when it didn't
• Visible — users can spot when verification was skipped and intervene early

This is the NTP of the synthesis project management system: periodic, authoritative-source-driven, automatic.