--- name: end-session description: > 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. allowed-tools: 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..md` using the pre-gathered date and timestamp values. Write the file using this format: ```markdown # Session Log -- YYYY-MM-DD ## Summary ## Decisions - Decision: -- Rationale: ## Gotchas Discovered - **[topic]** Symptom: -- Fix: ## Open Questions - ## Key Context - ## Process Notes - ``` **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: 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-.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/.md`, then upload to the most relevant item(s) with: ```bash python3 -m lib.cp_cli planner items documents put .md --file /tmp/.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 --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/.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--.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--.md`, where `` is the date the incident *occurred* (not today, if determinable from git history/logs) and `` 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 rca--.md --file ` - CP unreachable but the store has a local git checkout: write the file directly under `by-uuid//rca--.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--.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--.md`, where `` is the date the incident *occurred* (not today, if determinable from git history/logs) and `` 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 rca--.md --file ` - CP unreachable but the store has a local git checkout: write the file directly under `by-uuid//rca--.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/.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