session-checkpoint

---

name: session-checkpoint description: Saves session state before context compaction, task switching, or ending a session. Triggers: '/session-checkpoint', 'checkpoint', 'compact', 'save progress', 'end session', 'handoff', '체크포인트', '핸드오프 저장', '컴팩트 전에', '세션 저장', '세션 체크포인트'. Runs 5-phase pipeline: context extraction → entity classification → handoff write → memory save → preservation check → compact guidance. Use when this capability is needed. metadata: author: AlexZio00

Session Checkpoint

Dominant Variable

Has what the next session must know been clearly identified? If that identification is incomplete, go deeper on Phase 1 — compact comes after.

Discard If

• No code changes and no open decisions this session → compact not needed
• Already ran checkpoint this session → skip, no duplicate
• Only want to update the handoff file directly → edit memory/session-handoff-LATEST.md manually

---

Core Principles

• Handoff is a single file (memory/session-handoff-LATEST.md) — no version numbers
• Completed items get deleted, not archived
• The next session must be able to start from this file alone
• Preservation check before compact — always

---

Phase 1: Deep Context Extraction

Extract what compact could destroy. Full Compact preserves these 9 categories — cover all that apply:

• Open decisions — discussed but not resolved
• Current work state — what is in-progress right now (file, function, where you left off)
• User priority signals — what was emphasized, repeated, or caused friction → save as feedback memory
• Key tech concepts — new patterns, APIs, architecture insights discovered this session
• File paths + code snippets — specific files modified, function names, critical code fragments (compact loses these)
• Errors + fixes — error messages encountered and how they were resolved
• Current mental model — code flow, bug causation, failed approaches and why they failed
• Next steps — concrete actions for next session (with commands if applicable)
• Dead ends — approaches tried and abandoned this session (prevent repetition next session)

---

Phase 1.5: Entity Extraction

Auto-trigger recommendation (heuristic): Accumulated tokens ≥ 5,000 AND tool calls ≥ 3 AND ≥ 24h since last checkpoint → When all three conditions hit simultaneously, checkpoint is recommended. Same criteria apply on manual invocation.

Scan the session conversation for four entity types:

① Permanent fact candidates → promote to memory/MEMORY.md

• Newly discovered file paths / function names / architecture decisions
• New external tools / APIs / libraries (confirm installed)
• New hard rules or constraints
• Criterion: still true next session

② Episode entries → append to memory/context-log.md (TTL tag required)

• Completion events, external events, future plans
• TTL rules: ttl:permanent (decisions/architecture) | ttl:90d (completions/plans) | ttl:30d (temporary states)
• Format: [DATE] [TYPE] [ttl:Nd] [ref:0] description

③ Raw observations / patterns → preserve exact user phrasing

• Insights, judgments, or frustrations expressed directly by the user
• Candidates for tasks/lessons.md if they describe a repeated mistake
• lessons.md v2 metadata enrichment: For new lessons, add a metadata line below the header: > conf: 0.5 · seen: today · obs: 1. On re-observation/re-application of an existing lesson, update seen to today and increment obs. After obs reaches 3 / 6 / 9, raise conf by +0.1 (max 0.9). On user correction after a violation, lower conf by -0.1 (min 0.3) and update seen.

④ Stale detection → force MEMORY.md promotion

• Items in memory/context-log.md with [ref:N] where N ≥ 3 → check if they belong in MEMORY.md
• Same entity appearing 3+ times → add to MEMORY.md if not already there

⑤ Optional: Snapshot Cleanup (90-day policy)

If your project has a snapshots directory for session state snapshots, optionally check for outdated files:

• Files older than 90 days can typically be archived or deleted
• This is optional and only relevant if your project maintains such a directory
• Not applicable to most projects; skip if not using snapshots

---

Phase 1.6: Repeated Workflow Detection

Purpose: detect repeated manual workflows that could be promoted to a reusable skill. The point where "manual repetition 3 times" signals "this should become a skill call".

Scan this session's tool calls and user messages for repeated workflow signatures.

Signature definition: Three elements of the same workflow must be similar:

1. Intent — user request type (review / analyze / verify / generate / deploy)
2. Tool Sequence — executed tool-call pattern (e.g., Read → Grep → Edit → Bash test)
3. Output Shape — final deliverable form (report / code change / file creation)

Detection triggers (either one):

• Within-session repetition: same signature executed ≥ 3 times this session
• Cross-session accumulation: [ref:N] in memory/context-log.md for the same task type ≥ 5

Output format when detected:

[Repeated workflow candidate detected]
- Signature: {Intent} + {Tool Sequence} + {Output Shape}
- Frequency: {N} this session / {M} accumulated
- Suggestion: this workflow might benefit from a dedicated skill
- Proposed skill name: {snake_case_name}
- Proposed triggers: {trigger phrases — 3 examples}

Non-trigger conditions (skip proposal):

• One-off exploration (single Glob → Read)
• Signature duplicates an existing skill — scan ~/.claude/skills/*/SKILL.md to confirm
• Signature is too generic → would collide with an already-established skill

Promotion workflow: Proposal only. Never author the skill automatically. If user approves ("yes" / "approve" / "make it") → user invokes their skill-authoring workflow. If user declines ("no" / "pass" / "skip") → drop proposal, optionally log to tasks/lessons.md for future reference.

---

Phase 2: Write Handoff (single file update)

File: memory/session-handoff-LATEST.md

Rules

1. Read the previous handoff first (auto-loaded above) — remove completed items
2. Update status of in-progress items
3. Add newly surfaced items
4. Do not archive completed items — just delete them. Git history preserves them.

Required Sections

## Next Actions (priority order)
1. [most urgent] — include the exact command or step to start
2. [next]

## Current Work State  ← Full Compact 2nd priority required
- In-progress work: [file, function, where you left off]
- Omit section if nothing in-progress

## Open Decisions
- [topic]: [options] — user lean: [if known]

## Remaining Issues
- [unresolved bugs or blockers]

## Context Notes (needed next session)
- [important causation discovered this session]
- [approaches tried and failed — do not repeat]
- [critical file paths and function names — for post-compact recovery]

## Current Focus
- Top priority: [what]
- Friction: [what]

Forbidden

• Listing "what was done this session" — handoff is forward-looking only
• Version numbers (v1, v2, v3…)
• Keeping completed items
• Exceeding 200 lines

---

Phase 3: Save Memory

Apply Phase 1.5 extraction results to files:

1. memory/MEMORY.md — add permanent fact candidates to the relevant section (rewrite section, never append raw)
   • Check for duplicates before adding (skip or update if already present)
   • Stale items (contradicted by current state) → fix immediately
2. memory/context-log.md — append episode entries (date + TTL + ref:0 format required)
3. tasks/lessons.md — add behavior correction rules triggered this session (only if a real mistake occurred). If the file does not exist, create it first with a minimal header before writing:

   # Lessons
   <!-- conf scale: 0.3 (tentative) → 0.5 (moderate) → 0.7+ (verified) -->
   <!-- Format: ### [YYYY-MM-DD] Title / > conf: X · seen: YYYY-MM-DD · obs: N / body -->
   

   • v2 format: For new lessons, the header ### [YYYY-MM-DD] title is followed by a metadata line > conf: 0.5 · seen: YYYY-MM-DD · obs: 1
   • On re-observation: locate the existing lesson header → update seen to today, increment obs. After obs reaches 3 / 6 / 9, raise conf by +0.1 (max 0.9)
   • On violation + user correction: lower conf by -0.1 (min 0.3), update seen to today
   • Periodic cleanup (optional): conf < 0.4 AND (today − seen) > 90 days → move to archive folder
   • Backward compatible: lessons without v2 metadata are unchanged
4. Remove references to old handoff filenames in MEMORY.md index; unify to LATEST.
5. Optional cross-project state file — if your project maintains a STATE.md or similar cross-project state:
   • Resolved blockers → remove the entry
   • Completed items → remove the entry
   • Major milestones → optionally add to changelog
   • No change → skip entirely (do not touch)

---

Phase 4: Preservation Check

Checklist before compact:

□ Open decisions are in the handoff?
□ Session feedback saved to memory?
□ Next session can start from handoff alone?
□ In-progress code changes are described?
□ User's last request is complete or recorded?
□ STATE.md reviewed? (skip if no state change this session)

Any NO → fix before proceeding.

---

Phase 5: Compact Guidance

⚠ NO_TOOLS mode: /compact disables all tools during compression — no file reads or writes occur. All Phase 1–4 data must be persisted to files BEFORE running /compact.

/compact is a Claude Code CLI built-in — this skill cannot call it directly. After passing the checklist, tell the user:

"Checkpoint complete. Run /compact to compress context. Handoff: memory/session-handoff-LATEST.md"

---

Safety Layers

Risky Action	Notes
Overwriting MEMORY.md existing sections	Read current content first; overwrite section in place, never append raw
Deleting state entries	Verify the condition was actually met before removing
Workflow promotion to skill	Proposal only — user must explicitly approve before any skill is created

Truthful Reporting

After saving files:

1. Report "saved" only after verifying the write succeeded (file size / line count).
2. Phase 4 checklist items actually skipped → mark ⚠️ SKIPPED: reason. No phantom passes.
3. Final status: WORKING (all 5 phases complete) / PARTIAL (specific gaps listed) / BROKEN (handoff save failed).

---

Scope Boundary

Does	Does NOT
[WRITE] Record incomplete items in handoff file	Preserve completed items (delete is correct)
[EDIT] Update MEMORY.md with new/stale items	Write code or implement features
[READ] Run Phase 1–5 preservation checklist	Call /compact directly (CLI only)
[WRITE] Maintain single handoff file	Create versioned handoff files (v1, v2…)
[AGENT] Propose Crystallization candidates (Phase 1.6)	Author a new skill automatically (only after user approval)
[EDIT] Update STATE.md when state changes	Rewrite STATE.md content entirely

---

Invariants (never violate)

1. Single handoff file: only memory/session-handoff-LATEST.md exists. No versioned files (session-handoff-v2.md etc.). Violation → next session cannot determine which file is current, context recovery fails.

2. Forward-looking only: handoff must not list "what was done this session." Only "what to do next session." Violation → handoff becomes a changelog and the actual starting point is lost.

3. No compact guidance before preservation check: if any Phase 4 item is NO, do not tell the user to compress. Violation → incomplete work is lost in compression.

4. Workflow promotion proposes only, never executes: when Phase 1.6 detects a repeated workflow, it only suggests that a skill might be useful. Never auto-create a skill — user must explicitly decide and invoke a skill-authoring workflow. Violation → unnecessary skills generated from one-off exploration pollute the library.

---

Output

• memory/session-handoff-LATEST.md — incomplete items + open decisions + remaining issues only. Max 200 lines.
• Memory files — MEMORY.md updated for new/stale items (if applicable)
• Conversation — compact readiness confirmation + /compact instruction

---

Rationalization Table

Rationalization	Counter
"Completed items are useful for reference, keep them"	No. Keeping them turns the handoff into a changelog. Git history preserves them. Delete is the correct action.
"Phase 4 has one NO but it's probably fine..."	Invariant 3. The checklist exists precisely for this moment. NO state → do not guide compression.
"I'll save it as session-handoff-v2.md so we keep the old one too"	Invariant 1 violation. Git history keeps old versions. Versioned files cause "which one is current?" confusion that breaks context recovery.
"The session was short, Phase 1.5 isn't worth running"	Phase 1.5 takes 2 minutes. Missing one permanent fact means next session re-discovers it. Run it.
"Phase 1.6 detected a repetition — let me just author the skill right now"	Invariant 4 violation. User must judge whether the task will actually repeat. Auto-promotion turns one-off exploration into skills. Propose only.
"A repeated workflow was detected but the signature is too trivial, skip it"	If it matches Phase 1.6's "non-trigger conditions," fine. But dismissing 3+ repetitions as "trivial" is usually measurement laziness. Log it to context-log.md [ref:N] so the next session re-evaluates.

---

Pair

This skill is the closing half of the session lifecycle. /session-start → work → /session-checkpoint

Install both or neither — they are designed as a pair.

---

Proven In

Session handoff workflows across multi-week development projects. Once a codebase grows beyond ~200 files and multiple sessions span days, a single handoff file becomes the difference between "pick up immediately" and "20 minutes reconstructing context."

---

Source: AlexZio00/claude-code-skills — distributed by TomeVault.