# Alexzio00 Claude Code Skills Claude Code Skills > Session Checkpoint - Skill: `tomevault-io/alexzio00-claude-code-skills-claude-code-skills` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/alexzio00-claude-code-skills-claude-code-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/alexzio00-claude-code-skills-claude-code-skills/raw - Safety review: pending (external: skill-scanner FAIL, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/alexzio00-claude-code-skills-claude-code-skills --- # 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 ```markdown ## 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: ```markdown # Lessons ``` - **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](https://github.com/AlexZio00/claude-code-skills) — distributed by [TomeVault](https://tomevault.io).