feat(end-session): Step 2.3 planning-store status write-back
Session isn't finished until delivered work is written back to the project's canonical planning store (cp-cli / local checkout / offline staging), and roll-up docs are checked for contradictions. Motivated by the agent-runtimes work-items repo drifting 6 weeks behind delivered reality.
This commit is contained in:
Paul O'Reilly
243
skills/end-session/SKILL.md
Normal file
243
skills/end-session/SKILL.md
Normal file
@@ -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.<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.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user