handoff

/handoff — Save Context Before /clear

Create a structured handoff document to preserve context for seamless resumption.

When to Use

• Before /clear or /compact
• Context running low (hook may auto-trigger at 80%)
• End of work session
• Switching tasks temporarily

Handoff Document

Write to: thoughts/shared/handoffs/YYYY-MM-DD-{slug}-handoff.md

# Handoff: [Task Name]

Created: YYYY-MM-DD HH:MM Context Used: ~X% when created

Quick Summary

[2-3 sentences]

What's Done

• Item 1 (commit: abc123)
• Item 2 (commit: def456)

In Progress

• Current task
  • Done: [specifics]
  • Remaining: [specifics]

Not Started

• Remaining task 1
• Remaining task 2

Active Files

• src/auth/login.ts — line 45-80 needs completion
• tests/auth.test.ts — 3 passing, 2 pending

Key Decisions Made

1. Decision: [what] | Rationale: [why]

Important Discoveries

• [Thing learned during implementation]

Blockers / Open Questions

#	Question	Status
1	[Question]	Waiting on user

Beads State

[If .beads/ exists: run bd sync, capture in-progress and ready tasks]

Learnings & Suggested Updates

Analyze the session for patterns that should be captured for future sessions:

Commands & Workflows That Worked

• [Any CLI commands, tools, or workflows that were effective]

Pitfalls Encountered

• [Errors, gotchas, or mistakes that future sessions should avoid]

Assumptions That Were Wrong

• [Any initial assumptions that turned out to be incorrect]

Suggested CLAUDE.md / Rule Updates

• [Specific lines or sections that would have helped — be precise]

Suggested Instruction Updates

• [Changes to docs/instructions/ that would improve future sessions]

For each suggestion, be specific. BAD: "Update docs". GOOD: "Add to .claude/rules/community.md: 'Email handler imports db lazily — patch api._supabase.db in tests, not api.handlers.email.db'"

Next Steps (Prioritized)

1. Immediate: [First thing when resuming]
2. Then: [Second priority]

Resume

/restore @thoughts/shared/handoffs/YYYY-MM-DD-{slug}-handoff.md

## Process

1. Capture what's done (list completed tasks with commits)
2. Capture in-progress work (where exactly did you stop?)
3. Document key decisions and discoveries
4. Note blockers
5. Write prioritized next steps
6. Analyze session for learnings (see "Learnings & Suggested Updates" section)
7. If beads: `bd sync`
8. Commit handoff: `docs: create handoff for [feature]`
9. Review learnings and propose lesson saves (see Feedback Loop below)

## Feedback Loop: Propose Lesson Saves

After writing and committing the handoff document, review the "Learnings & Suggested Updates" section:

1. Scan for learnings that were encountered or noted **2+ times** during the session
   (e.g., a pitfall hit repeatedly, a workaround used more than once, a wrong assumption corrected and then referenced again)
2. Mark each repeated learning as a **lesson candidate**
3. Present proposals to the user:

I noticed these patterns during our session. Want me to save any as lessons?

1. [Pattern summary] — encountered N times Target: docs/instructions/learned/{date}-{topic}.md

2. [Pattern summary] — encountered N times Target: docs/instructions/learned/{date}-{topic}.md

4. If the user approves, write the lesson to `docs/instructions/learned/{date}-{topic}.md` and commit
5. If no learnings had 2+ occurrences, skip this step silently — do not propose one-off observations

**Important**: Do NOT automatically edit CLAUDE.md or instruction files. Only write to `docs/instructions/learned/` when the user explicitly approves.

## Best Practices

- Create early (don't wait until context is exhausted)
- Be specific ("line 45 of login.ts" not "somewhere in login")
- Include reasoning (future you needs the "why")
- Commit immediately