VaibhavAher100 wrap-session
Prevents session history loss when users type /clear. Sets up a project-local /wrap slash command, or executes the wrap directly if the project already has the logging structure.
When to Use
- User says "wrap up", "log this session", "save before clear", or types
/wrap - User wants to set up session logging in a new project
- Project has a
_state.md/sessions/structure but no/wrapcommand yet
What /wrap Does
- Pre-flight check - warn before wrapping if 20+ uncommitted file deletions
- Determine session ID - scan
sessions/for today's files, increment to nextYYYY-MM-DD-NNN - Write session log - create
sessions/YYYY-MM-DD-NNN.mdwith a self-assessedconfidencerating (high/medium/low, consumed by/unwrap), then append tosessions/_index.jsonl - Overwrite living state doc - update
_state.mdatomically (tmp file, verify, rename) - Consume the change-ledger - summarize hook-captured file changes while their content is still in context, then clear the ledger
- Append to decision log - only if new cross-session structural decisions were made this session
- Update CLAUDE.md breadcrumb - sanitized sentinel block pointing at the new session
- Report - output
Session logged as \`. Safe to /clear.`
Three-Document System
| File | Purpose | Update pattern |
|---|---|---|
_state.md |
Current project health, open items, user preferences | Overwritten each session |
_decisions.md |
Locked-in cross-session decisions | Append-only - never delete |
sessions/YYYY-MM-DD-NNN.md |
Full session detail | Created once, immutable after |
Setting Up in a New Project
Step 1 - Create the logging structure
<logs-dir>/
_state.md # Living doc - overwritten each session
_decisions.md # Append-only decision log
sessions/
(empty - Claude fills this)
Seed _state.md with current project state. Seed _decisions.md with the header only.
Step 2 - Create the /wrap command
mkdir -p .claude/commands
Copy wrap.md from this skill into .claude/commands/wrap.md.
Adapt the three path comments at the top of the copied file:
<!-- SESSIONS_DIR: logs/sessions -->
<!-- STATE_DOC: logs/_state.md -->
<!-- DECISIONS_LOG: logs/_decisions.md -->
All other instructions in wrap.md are path-agnostic.
Step 3 - Invoke
/wrap
or
/project:wrap
Session Log Frontmatter
---
schema_version: 2
session_date: YYYY-MM-DD
session_id: YYYY-MM-DD-NNN
summary: one-line description
confidence: high # high|medium|low - self-assessed context completeness, see the rubric in wrap.md
status: complete
tags: [session]
files_changed: 0
open_items: 0
---
Common Mistakes
| Mistake | Fix |
|---|---|
/wrap not found |
File must be at .claude/commands/wrap.md, not .claude/wrap.md |
| Session ID collision | Always scan existing files before picking ID - never hardcode |
_state.md not updated |
Step 3 must overwrite, not append |
| Decision log bloated | Only append when a genuine cross-session structural decision was made |
Wrap run after /clear |
Too late - context is gone. Always /wrap before /clear |
Two sessions /wrap at once |
IDs are scan-then-write - parallel wraps can collide on the same NNN. Run one at a time |
| Wrong paths in wrap.md | Adapt the three path comments at the top of wrap.md to match your project |