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

---
name: end-session
description: >
  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.
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.<HHMMSS>.md` using the pre-gathered date and timestamp values.

Write the file using this format:

```markdown
# 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