Skill v1.0.1
currentAutomated scan100/100+1 new
version: "1.0.1" 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." user_invocable: true context: !cat memory/session-handoff-LATEST.md
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.mdmanually
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.mdif 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, updateseento today and incrementobs. After obs reaches 3 / 6 / 9, raiseconfby +0.1 (max 0.9). On user correction after a violation, lowerconfby -0.1 (min 0.3) and updateseen.
④ Stale detection → force MEMORY.md promotion
- Items in
memory/context-log.mdwith[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:
- Intent — user request type (review / analyze / verify / generate / deploy)
- Tool Sequence — executed tool-call pattern (e.g., Read → Grep → Edit → Bash test)
- 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]inmemory/context-log.mdfor 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.mdto 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
- Read the previous handoff first (auto-loaded above) — remove completed items
- Update status of in-progress items
- Add newly surfaced items
- 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 start2.[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:
- `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
- `memory/context-log.md` — append episode entries (date + TTL + ref:0 format required)
- `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:
``markdown # 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] titleis followed by a metadata line> conf: 0.5 · seen: YYYY-MM-DD · obs: 1 - On re-observation: locate the existing lesson header → update
seento today, incrementobs. After obs reaches 3 / 6 / 9, raiseconfby +0.1 (max 0.9) - On violation + user correction: lower
confby -0.1 (min 0.3), updateseento today - Periodic cleanup (optional):
conf < 0.4 AND (today − seen) > 90 days→ move to archive folder - Backward compatible: lessons without v2 metadata are unchanged
- Remove references to old handoff filenames in MEMORY.md index; unify to LATEST.
- 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:/compactdisables 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:
- Report
"saved"only after verifying the write succeeded (file size / line count). - Phase 4 checklist items actually skipped → mark
⚠️ SKIPPED: reason. No phantom passes. - 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)
- Single handoff file: only
memory/session-handoff-LATEST.mdexists. No versioned files (session-handoff-v2.mdetc.). Violation → next session cannot determine which file is current, context recovery fails.
- 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.
- 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.
- 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 +
/compactinstruction
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."