/wrap-up
What
The session continuity ritual. Sessions are ephemeral; knowledge is permanent.
Wrap-up bridges sessions in both directions:
- Session END — capture exactly three things: what was DONE, what is
PENDING, and what was LEARNED. Write them to
.claude/handoff.md and flow
durable learnings into MEMORY.md.
- Session START — load the handoff, memory, and instincts, then present a
resume summary so no session starts blind.
When
- End of a working session — "done for today", "that's all", "signing off"
- Before switching projects or after a major milestone
- Implicit endings — "thanks" after completed tasks, "good enough for now":
offer the handoff, don't just say goodbye
- Start of a session — "start session", "load handoff", "what were we working on"
- For a mid-session save without ending, use
/checkpoint instead
How
Session End
- Review the session — From git status/diff and the conversation: files
touched, tasks completed vs unfinished, decisions made and why, user
corrections observed.
- Check uncommitted changes — If any exist, offer to commit before wrapping.
- Write the handoff —
.claude/handoff.md, using the format below.
Single file, always overwritten — only the current state matters. If the
existing handoff has pending tasks from someone else, ask before
overwriting: merge, overwrite, or skip.
- Extract learnings — Corrections and discoveries worth keeping go to
MEMORY.md (via instinct-system); emerging patterns update
.claude/instincts.md (via instinct-system). The handoff's Learned
section is the trigger, not the destination — handoffs are ephemeral.
- Confirm — Summarize the handoff and learnings captured for the user.
Handoff File Format (.claude/handoff.md)
Write it for a stranger with zero context — file paths, rationale, specific
next steps. "Continue the refactor" is useless; "Refactor
src/Orders/CreateOrder.cs to the Result pattern — see Catalog for the
established pattern" is actionable.
# Session Handoff
> Generated: 2026-06-12 | Branch: feature/order-validation
## Completed
- [x] Added FluentValidation to CreateOrder (src/Orders/Features/CreateOrder.cs:15-35)
- [x] Fixed N+1 in GetOrderDetails (src/Orders/Features/GetOrderDetails.cs:28)
## Pending
- [ ] Add validation to UpdateOrder (src/Orders/Features/UpdateOrder.cs)
- Reference: CreateOrder validator for the established pattern
- [ ] Full test run — 2 pre-existing Catalog failures, not from today
## Learned
- FluentValidation validators must be registered in the module's DI setup
- Test fixture seeds 1 item per order, which hides N+1 queries
## Context
- Branch: feature/order-validation | Last commit: "Add CreateOrder validation"
- Uncommitted changes: no | Solution: src/MyApp.slnx
When multiple developers share the project, add a ## Decisions Made table
(Decision | Choice | Rationale) and ## Open Questions.
Learning Extraction Checklist
- Did the user correct anything? → MEMORY.md via
instinct-system
- Did we discover something non-obvious? → Learned section
- Did we decide something with rationale? → document the "why"
- Did a tool/approach fail? → note it so the next session doesn't retry it
Good learning: "EF compiled queries don't work with Include()". Bad learning:
"Worked on Orders module" (vague) or "Used TimeProvider" (already a rule).
Session Start
- Load context — Read
.claude/handoff.md (pending work), MEMORY.md
(permanent rules), .claude/instincts.md (patterns at 0.7+ confidence).
Missing files are fine: note it and start clean — never block on them.
- Detect the solution — Find
.slnx/.sln (current dir, then parents,
then children) so Roslyn MCP tools work from the first prompt.
- Present a resume summary — Last session's work, pending tasks, active
rules/instincts count, detected solution. Then ask what to work on —
never auto-start pending work.
Example
User: /wrap-up
Claude: Wrapping up session...
## Session Summary
- Implemented OrderService with validation pipeline
- Fixed N+1 query in GetOrdersByCustomer
## Pending
- [ ] Add retry logic to payment gateway calls (OrderService.cs:42)
## Learnings Captured
- User prefers explicit mapping over AutoMapper → MEMORY.md
Written to .claude/handoff.md. See you next session.
Related
/checkpoint — Mid-session save (commit + brief note) without ending the sessioninstinct-system — Routes session learnings: patterns become instincts, user corrections become permanent MEMORY.md rules
1---
2name: wrap-up
3description: >
4 Owns the session handoff lifecycle: the end-of-session ritual that captures
5 completed work, pending tasks, and learnings into .claude/handoff.md, and the
6 session-start protocol that loads it back. Triggers on: /wrap-up, "wrap up",
7 "done for today", "that's all", "end session", "signing off", "handoff" —
8 and at session start: "start session", "session start", "load handoff",
9 "pick up where we left off", "what were we working on".
10disable-model-invocation: true
11---
12
13# /wrap-up
14
15## What
16
17The session continuity ritual. Sessions are ephemeral; knowledge is permanent.
18Wrap-up bridges sessions in both directions:
19
20- **Session END** — capture exactly three things: what was DONE, what is
21 PENDING, and what was LEARNED. Write them to `.claude/handoff.md` and flow
22 durable learnings into `MEMORY.md`.
23- **Session START** — load the handoff, memory, and instincts, then present a
24 resume summary so no session starts blind.
25
26## When
27
28- End of a working session — "done for today", "that's all", "signing off"
29- Before switching projects or after a major milestone
30- Implicit endings — "thanks" after completed tasks, "good enough for now":
31 offer the handoff, don't just say goodbye
32- Start of a session — "start session", "load handoff", "what were we working on"
33- For a mid-session save without ending, use `/checkpoint` instead
34
35## How
36
37### Session End
38
391. **Review the session** — From git status/diff and the conversation: files
40 touched, tasks completed vs unfinished, decisions made and why, user
41 corrections observed.
422. **Check uncommitted changes** — If any exist, offer to commit before wrapping.
433. **Write the handoff** — `.claude/handoff.md`, using the format below.
44 Single file, always overwritten — only the current state matters. If the
45 existing handoff has pending tasks from someone else, ask before
46 overwriting: merge, overwrite, or skip.
474. **Extract learnings** — Corrections and discoveries worth keeping go to
48 `MEMORY.md` (via `instinct-system`); emerging patterns update
49 `.claude/instincts.md` (via `instinct-system`). The handoff's Learned
50 section is the trigger, not the destination — handoffs are ephemeral.
515. **Confirm** — Summarize the handoff and learnings captured for the user.
52
53### Handoff File Format (`.claude/handoff.md`)
54
55Write it for a stranger with zero context — file paths, rationale, specific
56next steps. "Continue the refactor" is useless; "Refactor
57`src/Orders/CreateOrder.cs` to the Result pattern — see Catalog for the
58established pattern" is actionable.
59
60```markdown
61# Session Handoff
62
63> Generated: 2026-06-12 | Branch: feature/order-validation
64
65## Completed
66- [x] Added FluentValidation to CreateOrder (src/Orders/Features/CreateOrder.cs:15-35)
67- [x] Fixed N+1 in GetOrderDetails (src/Orders/Features/GetOrderDetails.cs:28)
68
69## Pending
70- [ ] Add validation to UpdateOrder (src/Orders/Features/UpdateOrder.cs)
71 - Reference: CreateOrder validator for the established pattern
72- [ ] Full test run — 2 pre-existing Catalog failures, not from today
73
74## Learned
75- FluentValidation validators must be registered in the module's DI setup
76- Test fixture seeds 1 item per order, which hides N+1 queries
77
78## Context
79- Branch: feature/order-validation | Last commit: "Add CreateOrder validation"
80- Uncommitted changes: no | Solution: src/MyApp.slnx
81```
82
83When multiple developers share the project, add a `## Decisions Made` table
84(Decision | Choice | Rationale) and `## Open Questions`.
85
86### Learning Extraction Checklist
87
881. Did the user correct anything? → MEMORY.md via `instinct-system`
892. Did we discover something non-obvious? → Learned section
903. Did we decide something with rationale? → document the "why"
914. Did a tool/approach fail? → note it so the next session doesn't retry it
92
93Good learning: "EF compiled queries don't work with Include()". Bad learning:
94"Worked on Orders module" (vague) or "Used TimeProvider" (already a rule).
95
96### Session Start
97
981. **Load context** — Read `.claude/handoff.md` (pending work), `MEMORY.md`
99 (permanent rules), `.claude/instincts.md` (patterns at 0.7+ confidence).
100 Missing files are fine: note it and start clean — never block on them.
1012. **Detect the solution** — Find `.slnx`/`.sln` (current dir, then parents,
102 then children) so Roslyn MCP tools work from the first prompt.
1033. **Present a resume summary** — Last session's work, pending tasks, active
104 rules/instincts count, detected solution. Then ask what to work on —
105 never auto-start pending work.
106
107## Example
108
109```
110User: /wrap-up
111
112Claude: Wrapping up session...
113
114## Session Summary
115- Implemented OrderService with validation pipeline
116- Fixed N+1 query in GetOrdersByCustomer
117
118## Pending
119- [ ] Add retry logic to payment gateway calls (OrderService.cs:42)
120
121## Learnings Captured
122- User prefers explicit mapping over AutoMapper → MEMORY.md
123
124Written to .claude/handoff.md. See you next session.
125```
126
127## Related
128
129- `/checkpoint` — Mid-session save (commit + brief note) without ending the session
130- `instinct-system` — Routes session learnings: patterns become instincts, user corrections become permanent MEMORY.md rules
codewithmukesh