custom-claude-skills/skills/end-session/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
end-session	End-of-session wrap-up. Captures a session log, updates CONTEXT.md for seamless resumption, and refreshes project docs (README, CLAUDE.md, FUTURE.md) with anything that changed this session. Just run /end-session when you're done working.	Read, Edit, Write, Grep, Glob, Bash(git log *), Bash(git diff *), Bash(date *), Bash(ls *), Bash(cat *), Bash(find *), Bash(rm *), Bash(mkdir *), Bash(sed *), Bash(python3 -m lib.cp_cli *)

End-of-Session Skill

You are wrapping up a session. This skill captures a session log, updates CONTEXT.md for resumption, and refreshes project documentation with changes from this session.

Pre-gathered context

Current date and session timestamp

!date +%Y-%m-%d !date +%Y%m%d-%H%M%S

Git log (last 30 commits)

!git log --oneline -30 2>/dev/null || echo "Not a git repo"

Git status

!git status --short 2>/dev/null || echo "Not a git repo"

Current MEMORY.md

!cat MEMORY.md 2>/dev/null || echo "No MEMORY.md found"

Current CONTEXT.md

!cat CONTEXT.md 2>/dev/null || echo "No CONTEXT.md found"

Current FUTURE.md

!cat FUTURE.md 2>/dev/null || echo "No FUTURE.md found"

Current README.md (scripts section)

!sed -n '/## Scripts/,/^## /p' README.md 2>/dev/null | head -60 || echo "No Scripts section found"

Current README.md (milestone table)

!sed -n '/## Milestones/,/^## /p' README.md 2>/dev/null | head -40 || echo "No Milestones section found"

Available scripts

!ls -1 scripts/ 2>/dev/null || echo "No scripts directory"

Existing log files

!ls -1 memory/log/ 2>/dev/null || echo "No log directory yet"

Reflection state

!cat .reflection-state.json 2>/dev/null || echo "No reflection state yet"

Settings

(Read ~/dev/claude/projects/claude-foundations/settings.yaml using the Read tool. If not found, use defaults: retention_days=7, warn_unreflected_days=14)

---

Phase 1: Session Log

Step 1.1: Create the log directory if needed

If memory/log/ does not exist, create it with mkdir -p memory/log/.

Step 1.2: Write the log file

Review the full conversation history and extract key points worth preserving. If the session was trivial (a typo fix, a quick question), note that and write a minimal log.

Generate the filename as memory/log/YYYY-MM-DD.<HHMMSS>.md using the pre-gathered date and timestamp values.

Write the file using this format:

# Session Log -- YYYY-MM-DD

## Summary
<!-- 1-2 sentence overview of what was accomplished -->

## Decisions
<!-- Omit section if none -->
- Decision: <what> -- Rationale: <why>

## Gotchas Discovered
<!-- Omit section if none -->
- **[topic]** Symptom: <what happened> -- Fix: <what resolved it>

## Open Questions
<!-- Omit section if none -->
- <question>

## Key Context
<!-- Omit section if none -->
- <fact>

## Process Notes
<!-- Omit section if none -->
- <note>

Guidelines:

• Omit empty sections entirely
• [topic] tags on gotchas should match existing memory topic names where possible
• Keep entries concise -- raw material for /reflect-logs

Step 1.3: Prune old logs

1. Read retention_days and warn_unreflected_days from settings (defaults: 7 and 14)
2. Read .reflection-state.json to know which logs have been reflected on
3. For each file in memory/log/:
   • Parse the date from the filename (first 10 characters: YYYY-MM-DD)
   • If older than retention_days AND present in .reflection-state.json -- delete it
   • If older than warn_unreflected_days AND NOT in .reflection-state.json -- warn: WARNING: <filename> is N days old and has NOT been reflected on. Run /reflect-logs.
   • Otherwise -- leave it alone

---

Phase 2: Update CONTEXT.md

This is the most important phase for session resumption. CONTEXT.md tells the next session what to focus on.

Step 2.1: Assess current state

Based on the full conversation, determine:

• What work is actively in progress (not yet complete)?
• What was completed this session that changes the project's focus?
• What should the next session pick up first?
• Are there blockers, pending decisions, or things to verify?

Step 2.2: Update CONTEXT.md and context/ files

Follow the thin-index pattern:

1. Remove completed entries from CONTEXT.md that are no longer active.

2. Add or update entries for active work streams, linking to detail files in context/.

3. Create or update context/<topic>.md files with enough detail for a fresh session to resume without re-reading the full conversation:

   • What's the current state?
   • What was the last thing done?
   • What should be done next?
   • Any gotchas, blockers, or decisions pending?
   • Key file paths, commands, or references needed to continue.

4. If context/ directory doesn't exist and there are active work streams, create it with mkdir -p context/.

Principles:

• Write for a Claude session that has zero conversation history -- it only has CONTEXT.md and the linked files.
• Be specific: file paths, branch names, error messages, command sequences.
• Don't duplicate what's in CLAUDE.md or MEMORY.md -- reference those instead.
• If there's nothing active (session wrapped up cleanly with no follow-up), say so in CONTEXT.md: No active work streams. Project is at a clean stopping point.

Step 2.3: Planning-store status write-back

If the project's CLAUDE.md declares a canonical planning store outside the repo (e.g. a work-items repo managed via cp-cli planner items …, like agent-runtimes-work-items), the session is not finished until delivered work is written back to it. Stale planning stores mislead every future session and agent that treats them as canonical.

1. List what this session delivered or advanced: milestones completed or progressed, epics affected, specs shipped, pipelines deployed.
2. For each affected item, update its status in the planning store:
   • CP reachable: update the item's flow state / status document via cp-cli planner items … / documents put (see the project CLAUDE.md for the exact workflow).
   • CP unreachable but the store has a local git checkout: edit the status/plan/CONTEXT docs there directly and note in CONTEXT.md that the edit needs upload/push.
   • Neither: stage the update in the project's offline staging dir (e.g. local-planning/<item-uuid>/) and record the pending upload in CONTEXT.md.
3. Check roll-up documents for contradictions: any epic overview, delivery map, or roadmap doc that summarises the affected milestones must not now contradict reality (e.g. still saying "pending" for work that shipped this session). Fix the rows you have ground truth for; flag the ones you don't.
4. If nothing this session touched milestone/epic-level state, say so and move on.

Skip this step entirely only when the project has no external planning store.

Step 2.4: RCA document write-back

If this session root-caused a real incident — a bug, outage, or regression with a clear symptom, root cause, and fix, not just routine debugging — and the project's planning store supports an incident item type (check the store's DATA_VALUES.md/CLAUDE.md for an incident type and an rca-<date>-<slug>.md naming convention; most projects will not have this, in which case skip this step entirely):

1. Find or create the incident item. Search the planning store for an existing type: incident item covering this incident before creating a new one.
2. Write the full postmortem as rca-<date>-<slug>.md, where <date> is the date the incident occurred (not today, if determinable from git history/logs) and <slug> is a short kebab-case description. Cover symptom, root cause, fix, and impact — this is the durable narrative; the item's CONTEXT.md body stays a short summary.
3. Upload it to the incident item:
   • CP reachable: python3 -m lib.cp_cli planner items documents put <incident-item-uuid> rca-<date>-<slug>.md --file <path>
   • CP unreachable but the store has a local git checkout: write the file directly under by-uuid/<incident-item-uuid>/rca-<date>-<slug>.md there and note in CONTEXT.md that it needs a commit/push.
   • Neither: stage it in the project's offline staging dir (e.g. local-planning/) and record the pending upload in CONTEXT.md.
4. Link every affected item to the incident via the impacted/impacted_by relationship verb (or whatever the store's DATA_VALUES.md names it) — one document on the incident item, one relationship edge per affected item, not copies of the document.
5. If nothing this session rises to postmortem-worthy, skip this step and say so.

---

Phase 3: Update Project Documentation

Review the conversation for changes that should be reflected in project docs. Only update files where this session actually changed something relevant -- don't touch files that are already accurate.

Step 3.1: FUTURE.md

If new improvement ideas, feature requests, or tech debt surfaced during this session, add them to FUTURE.md using the standard format:

• Problem: What's painful or manual today
• Idea: What the improvement looks like
• Open questions: Unknowns to research before starting
• Depends on: Other items or milestones that should come first

Skip this step if no new ideas emerged.

Step 3.2: README.md

Update if any of these changed this session:

• Milestone table -- update status if a milestone progressed or completed
• Scripts section -- add any new scripts created this session (with purpose and usage)
• Setup instructions -- if new dependencies, environment changes, or setup steps were introduced

Skip this step if README.md is already accurate.

Step 3.3: CLAUDE.md (and claude/ detail files)

Update if any of these changed this session:

• Repo structure -- new directories, moved files, renamed components
• Conventions -- new patterns or rules discovered during implementation
• Environment details -- new URLs, IPs, service endpoints, credentials references
• Common operations -- new how-to recipes worth preserving

If the project follows the thin-index pattern (a claude/ directory with per-topic detail files referenced from CLAUDE.md), put per-subsystem changes in the appropriate claude/<topic>.md file rather than the root CLAUDE.md. Only edit the root CLAUDE.md for always-applies guardrails, the architecture overview, or the pointer table itself (e.g., adding a row for a new detail file).

Skip this step if CLAUDE.md and the relevant detail file are already accurate.

---

Phase 4: Summary

Print a concise summary:

Session log:

• Log file path created
• Number of entries by section
• Any files pruned or warnings issued

Context update:

• What CONTEXT.md now points to (active work streams)
• What the next session should pick up

Doc updates:

• Which files were updated (FUTURE.md, README.md, CLAUDE.md) and what changed
• Or "No doc updates needed" if everything was already accurate

---

Quality Checks

• Gotchas include symptom AND fix, not just "X was tricky"
• Process lessons are phrased as rules ("Always X before Y")
• CONTEXT.md entries are specific enough to resume from without conversation history
• Context detail files include file paths, branch names, and next steps
• Future items have all four fields (Problem/Idea/Open questions/Depends on)
• Doc updates are minimal and accurate -- only touch what actually changed this session
• README scripts section lists every script with purpose and usage