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

---
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.<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 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:
   ```bash
   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