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:
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.
Count unresolved entries in
.context/kb/outstanding-questions.md (rows whose Status
is open).
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"
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:
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-digestnext 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:
Title: a short noun phrase naming the session arc
(becomes the slug in <TS>-<slug>.md). Drawn from the
conversation; confirm with the user.
--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.
--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.
--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.
--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:
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