diff --git a/skills/end-session/SKILL.md b/skills/end-session/SKILL.md new file mode 100644 index 0000000..6df82c9 --- /dev/null +++ b/skills/end-session/SKILL.md @@ -0,0 +1,243 @@ +--- +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 *) +--- + +# 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 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/.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//`) 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. + +--- + +## 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 + +**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