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; for planner-backed projects writes a session status doc to the work-items store (the authoritative state source); updates CONTEXT.md as a thin cache for planner projects or fully for non-planner projects; 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 state — planning store (primary) or CONTEXT.md (fallback)

Detect whether the project has a planner: look for cp-cli planner in the project's CLAUDE.md. If found, the project has a live planner and Step 2.1 applies. Otherwise go to Step 2.2 (CONTEXT.md-only flow).

Long-term goal: for planner-backed projects, CONTEXT.md is being retired in favour of scripts/get_context as the authoritative live state source. Until it is removed, keep the CONTEXT.md "Current State" header updated as a thin cache — one line per major change — but do NOT write new narrative detail there. All narrative goes to work-items.

Step 2.1: Planning-store write-back (projects WITH a planner)

The session is not finished until delivered work is written back to the planner. scripts/get_context is what future sessions and agents see — stale items mislead them.

1. Assess what this session delivered or advanced: milestones progressed/completed, bugs fixed, features shipped, specs updated, pipelines deployed.

2. Write a session status document (session-YYYY-MM-DD-<slug>.md) capturing:

   • What was done and the key commits
   • Root causes / decisions / gotchas discovered
   • Current cluster/deployment state (image version, what's live)
   • What's next

   Write to /tmp/<name>.md, then upload to the most relevant item(s) with:

   python3 -m lib.cp_cli planner items documents put <item-uuid> <name>.md --file /tmp/<name>.md
   

   Upload to whichever item(s) the work actually belongs to (milestone, epic, bug, etc.). If the work spans multiple items, one doc is enough — upload it to the primary one.

3. Update item flow states for anything that completed this session:

   • python3 -m lib.cp_cli planner items update <uuid> --flow-state completed
   • If the planner doesn't support direct state updates, note it in the doc and skip.

4. Check roll-up documents for contradictions: any epic overview or delivery map that summarises affected milestones must not contradict reality after this session's changes. Fix what you have ground truth for; flag the rest.

5. Update CONTEXT.md as a thin cache only — find the "Current State" section and update just the cluster image version and a one-liner about what changed. Do NOT add new narrative sections. Resist the urge to expand CONTEXT.md; that information belongs in work-items. If CONTEXT.md doesn't exist yet, do not create it.

6. If nothing this session touched milestone/epic-level state, still write a brief session doc to the most relevant item so scripts/get_context --show-rca captures it.

Step 2.2: CONTEXT.md update (projects WITHOUT a planner)

For projects with no planner, CONTEXT.md is still the primary handoff mechanism.

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?

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.

Principles:

• Write for a Claude session with zero conversation history.
• 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: No active work streams. Project is at a clean stopping point.

Step 2.3: 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.

Skip this step entirely 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

State update:

• (planner project) Which items got a session doc uploaded; any flow-state changes; CONTEXT.md current-state one-liner
• (no-planner project) What CONTEXT.md now points to; 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")
• (planner) Session status doc is uploaded to the correct item; CONTEXT.md current-state is updated to one line
• (no-planner) CONTEXT.md entries are specific enough to resume from without conversation history; 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