• The session is long and Claude feels confused or repetitive
• Claude keeps trying the same failing solution over and over
• The user wants to step away and resume later

• /compact

  ran but Claude still lacks clear direction
• The user says "handoff", "generate a handoff", "I want to start fresh", or "write a handoff doc"

1. Goal — One paragraph. What is the user actually trying to accomplish? State the end state, not the current sub-task. Be specific enough that a fresh agent can orient immediately.
2. Current State — What is working right now? What is broken? What is the exact symptom of the problem? Include error messages verbatim if relevant.
3. Files in Play — List every file that has been read, edited, or created during this session that is relevant to the current task. Use absolute or repo-relative paths. Include a one-line note on why each file matters.
4. What Has Been Tried (and Why It Failed) — This is the most important section. List every approach attempted that did not work, and explain WHY it failed (not just that it failed). A fresh agent that skips this section will repeat the same mistakes.
5. Current Best Theory — What do you currently believe is the right path forward, even if you haven't proven it yet? Include any evidence or reasoning that supports it.
6. Next Steps — Concrete, ordered actions for the fresh agent to take. Be specific: file paths, function names, commands to run. The fresh agent should be able to start on step 1 immediately.
7. Key Constraints and Context — Any non-obvious constraints: environment specifics, user preferences expressed during this session, things the user explicitly said NOT to do, external dependencies, performance requirements, etc.
8. Memory Pointers — If claude-mem's search tools are available, run

   search

   for this task's key terms and list the few observation IDs that matter most (a decision, the root cause, a failed approach), so the fresh agent can pull full details with

   get_observations

   . Also list one or two

   search

   queries worth re-running. Skip this section if the tools are not available.

• Write the handoff for a fresh Claude, not for the user. The user knows what happened; the fresh Claude does not.
• Be ruthlessly specific. Vague next steps are useless. "Fix the auth" is bad. "In

  src/auth/middleware.ts:47

  , the token expiry check uses

  Date.now()

  but should use

  req.timestamp

  — change the comparison on line 52" is good.
• Include exact error messages, stack traces, or test output that captures the failure mode.
• Do not pad. Every sentence should be load-bearing information for the fresh agent.
• Do not write the handoff from the user's perspective. Write it as a briefing document addressed to the incoming agent.

Generated: [timestamp]
Project: [project name or directory]
Session summary: [one sentence describing what this session was about]

• [list what is confirmed working]

• [exact symptom, error message, or failure mode]

• What: [what was done]
• Why it failed: [root cause, not just "it didn't work"]

1. [Specific, actionable step with file path or command]
2. [Next step]
3. ...

• [Non-obvious constraint or preference the user expressed]
• [Things explicitly ruled out]

• Observations: [#ID — one line on why it matters]
• Searches worth re-running: [

  search

  query]

undefined

1. That

   HANDOFF.md

   has been written
2. To run

   /clear

   or start a new Claude Code session
3. To open the new session and say: "Read HANDOFF.md and continue from where we left off."
4. That claude-mem gives the fresh agent the recent timeline automatically, and

   HANDOFF.md

   is its precise briefing on top of that
5. That

   HANDOFF.md

   is a scratch file: don't commit it (delete it once the new session has picked up, or add it to

   .gitignore

   )