• 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.

• 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

1. Review the session — From git status/diff and the conversation: files touched, tasks completed vs unfinished, decisions made and why, user corrections observed.
2. Check uncommitted changes — If any exist, offer to commit before wrapping.
3. 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.
4. 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.
5. Confirm — Summarize the handoff and learnings captured for the user.

Generated: 2026-06-12 | Branch: feature/order-validation

• Added FluentValidation to CreateOrder (src/Orders/Features/CreateOrder.cs:15-35)
• Fixed N+1 in GetOrderDetails (src/Orders/Features/GetOrderDetails.cs:28)

• 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

• FluentValidation validators must be registered in the module's DI setup
• Test fixture seeds 1 item per order, which hides N+1 queries

• 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`.

1. Did the user correct anything? → MEMORY.md via

   instinct-system

2. Did we discover something non-obvious? → Learned section
3. Did we decide something with rationale? → document the "why"
4. Did a tool/approach fail? → note it so the next session doesn't retry it

1. 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.
2. Detect the solution — Find

   .slnx

   /

   .sln

   (current dir, then parents, then children) so Roslyn MCP tools work from the first prompt.
3. 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.

• Implemented OrderService with validation pipeline
• Fixed N+1 query in GetOrdersByCustomer

• Add retry logic to payment gateway calls (OrderService.cs:42)

• User prefers explicit mapping over AutoMapper → MEMORY.md

undefined

• /checkpoint

  — Mid-session save (commit + brief note) without ending the session

• instinct-system

  — Routes session learnings: patterns become instincts, user corrections become permanent MEMORY.md rules