ctx-wrap-up

name	ctx-wrap-up
description	End-of-session context persistence ceremony. Use when wrapping up a session to capture learnings, decisions, conventions, and tasks.

Guide end-of-session context persistence. Gather signal from the session, propose candidates worth persisting, and persist approved items via ctx add.

This is a ceremony skill: invoke it explicitly as /ctx-wrap-up at session end, not conversationally. It pairs with /ctx-remember at session start.

Before Starting

Check that the context directory exists. If it does not, tell the user: "No context directory found. Run ctx init to set up context tracking, then there will be something to wrap up."

Handover Is the Mandatory Final Step

/ctx-wrap-up owns the user-facing session-end trigger and always delegates to /ctx-handover as its final step. The handover is the former agent's note to the next agent (or human): what happened, and what should come next. It writes .context/handovers/<TS>-<slug>.md (timestamped so multiple agent runs never overwrite). Without this final step, /ctx-remember has nothing to read at the start of the next session and recall degenerates into probabilistic reconstruction from canonical files plus journal.

KB Editorial State (Phase KB, Optional)

If .context/kb/ exists, this project additionally uses the editorial pipeline. After the capture phase but before the final /ctx-handover delegation:

1. List any closeouts under .context/ingest/closeouts/. These are per-pass audit artifacts from /ctx-kb-ingest, /ctx-kb-ask, etc. that have not yet been folded into a handover.
2. Count unresolved entries in .context/kb/outstanding-questions.md (rows whose Status is open).
3. Surface both counts in the wrap-up summary so the operator sees what editorial residue is pending; the handover step's fold pass will consume the closeouts.

When .context/kb/ does NOT exist, skip this section entirely; the wrap-up proceeds with the standard capture checklist and still ends with /ctx-handover.

When to Use

• At the end of a session, before the user quits
• When the user says "let's wrap up", "save context", "end of session"
• When the check-persistence hook suggests it

When NOT to Use

• Nothing meaningful happened (only read files, quick lookup)
• The user already persisted everything manually with ctx add
• Mid-session when the user is still in flow: use /ctx-reflect instead for mid-session checkpoints

Process

Phase 1: Gather signal

Do this silently: do not narrate the steps:

1. Check what changed in the working tree:

   git diff --stat
   

2. Check commits made this session:

   git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline -5
   

3. Scan the conversation history for:
   • Architectural choices or design trade-offs discussed
   • Gotchas, bugs, or unexpected behavior encountered
   • Patterns established or conventions agreed upon
   • Follow-up work identified but not yet started
   • Tasks completed or progressed

Phase 2: Propose candidates

Think step-by-step about what is worth persisting. For each potential candidate, ask yourself:

• Is this project-specific or general knowledge? (Only persist project-specific insights)
• Would a future session benefit from knowing this?
• Is this already captured in the context files?
• Is this substantial enough to record, or is it trivial?

Present candidates in a structured list, grouped by type. Skip categories with no candidates: do not show empty sections.

## Session Wrap-Up

### Learnings (N candidates)
1. **Title of learning**
   - Context: What prompted this
   - Lesson: The key insight
   - Application: How to apply it going forward

### Decisions (N candidates)
1. **Title of decision**
   - Context: What prompted this
   - Rationale: Why this choice
   - Consequence: What changes as a result

### Conventions (N candidates)
1. **Convention description**

### Tasks (N candidates)
1. **Task description** (new | completed | updated)

Persist all? Or select which to keep?

Phase 3: Persist approved candidates

Wait for the user to approve, select, or modify candidates. Wait for the user to approve each item before persisting: candidates proposed by the agent may be incomplete or mischaracterized, and the user is the final authority on what belongs in their context.

For each approved candidate, run the appropriate command:

Type	Command
Learning	ctx learning add "Title" --session-id ID --branch BR --commit HASH --context "..." --lesson "..." --application "..."
Decision	ctx decision add "Title" --session-id ID --branch BR --commit HASH --context "..." --rationale "..." --consequence "..."
Convention	ctx convention add "Description"
Task (new)	ctx task add "Description" --session-id ID --branch BR --commit HASH
Task (done)	Edit TASKS.md to mark complete

Report the result of each command. If any fail, report the error and continue with the remaining items.

Phase 3.5: Suppress post-wrap-up nudges

After persisting, mark the session as wrapped up so checkpoint nudges are suppressed for the remainder of the session:

ctx system mark-wrapped-up

Phase 4: Surface Uncommitted Changes

After persisting, check for uncommitted changes:

git status --short

When git status --short reports any modified or untracked files, surface them and offer /ctx-commit:

There are uncommitted changes (<count> files). Run /ctx-commit to commit with context capture?

Do not auto-commit; the user decides. But always run the git status check and always surface non-empty output. Do not skip this phase silently when the working tree is dirty.

Phase 4.4: Surface knowledge health (suggest-only)

Run:

ctx system check-knowledge --report

When it prints findings, surface them as a closing suggestion: a foldable root → run /ctx-digest next session; a heavy page → split the theme or extract it to tooling. Prints nothing when every root is within limits — then say nothing.

Never fold inline here. The human is closing the laptop to go live their life; running a semantic pass at wrap-up is against their interest (spec: progressive-disclosure ### Triggers). This phase suggests for next session; it does not act.

Phase 4.5: Capture the session journal (best-effort)

Before handing over, sweep this session — and any others that have grown since their last import — into the journal so the next session can read it:

ctx journal import --all -y

This is growth-aware and idempotent: it imports the live session as far as it has progressed today and self-heals on the next run, so running it mid-wrap-up is safe and needs no flags beyond -y. Treat it as non-blocking — if it errors, note the error and continue to the handover anyway; a failed import must never block the handover. (A SessionEnd hook runs the same sweep automatically; this ceremony step is belt-and- suspenders.) Enrichment is a separate LLM pass (/ctx-journal-enrich-all) and is not part of wrap-up.

Phase 5: Delegate to /ctx-handover (mandatory)

/ctx-wrap-up always ends here. Drafting the handover reuses the signal gathered in Phase 1 and the candidates approved in Phase 3:

1. Title: a short noun phrase naming the session arc (becomes the slug in <TS>-<slug>.md). Drawn from the conversation; confirm with the user.
2. --summary (required, past tense): one paragraph naming what was done this session, drawn from the approved candidates and the git-log scan. Concrete, not vague.
3. --next (required, future tense): one paragraph naming the specific first action the next agent should take. Pull from the highest-priority pending task in TASKS.md or the open thread the session was on.
4. --highlights: draft a bullet list of notable artifacts produced this session (commits, decisions, specs, files created). Always present a draft. Pass an empty string only after the user has explicitly said there is nothing to highlight.
5. --open-questions: draft a bullet list of things that remain undecided. Pull from any candidate the user did not turn into a decision, any deferred ingest pass, any TODO discovered in the session. Always present a draft. Pass an empty string only after the user has explicitly confirmed there is nothing open.

Surface the drafted values to the user for one final confirmation, then delegate:

/ctx-handover "<title>" --summary "<...>" --next "<...>" \
  [--highlights "<...>"] [--open-questions "<...>"]

The /ctx-handover skill performs the pre-write gates, writes .context/handovers/<TS>-<slug>.md, and (when .context/kb/ exists) folds postdated closeouts into the ## Folded Closeouts section and archives them. See /ctx-handover for the full input contract and CLI flag reference.

If /ctx-handover refuses (missing .context/handovers/, empty placeholder values, etc.), surface the refusal to the user. Do not declare the wrap-up complete until the handover landed.

Candidate Quality Guide

Good candidates

• "PyMdownx details extension wraps content in <details> tags, breaking <pre><code> rendering in MkDocs": specific gotcha, actionable for future sessions
• "Decision: use file-based cooldown tokens instead of env vars because hooks run in subprocesses": real trade-off with rationale
• "Convention: all skill descriptions use imperative mood": codifies a pattern for consistency

Weak candidates (do not propose)

• "Go has good error handling": general knowledge, not project-specific
• "We edited main.go": obvious from the diff, not an insight
• "Tests should pass before committing": too generic to be useful
• Anything already present in LEARNINGS.md or DECISIONS.md

Relationship to /ctx-reflect

/ctx-reflect is for mid-session checkpoints at natural breakpoints. /ctx-wrap-up is for end-of-session: it's more thorough, covers the full session arc, and includes the commit offer. If the user already ran /ctx-reflect recently, avoid proposing the same candidates again.

Quality Checklist

Before presenting candidates, verify:

• Signal was gathered (git diff, git log, conversation scan)
• Every candidate has complete fields (not just a title)
• Candidates are project-specific, not general knowledge
• No duplicates with existing context files
• Empty categories are omitted, not shown as "(none)"
• User is asked before anything is persisted

After persisting, verify:

• Each ctx add command succeeded
• Uncommitted changes were surfaced (if any)
• User was offered /ctx-commit (if applicable)
• /ctx-handover was invoked and the resulting .context/handovers/<TS>-<slug>.md was written