• Ending a work session for the day
• Before taking a break mid-task
• Switching to a different project temporarily
• When you want to capture state for a future session
• Before a context reset you know is coming

1. What phase are we in? (exploration, planning, implementation, debugging, review)
2. What's the active task? (what we're trying to accomplish)
3. How far along are we? (just started, mid-way, almost done)

"I'll create a handoff document. Is there anything specific you want to make sure I capture? (Key decisions, code snippets, context about the problem, things you'll forget, etc.)"

• [Decision] — [Rationale]
• [Decision] — [Rationale]

• path/to/file.ts

  — [what and why]

• path/to/other.ts

  — [what and why]

• [Question needing resolution]
• [Question needing resolution]

• [Issue] — [current status]

1. [First thing to do next session]
2. [Second thing]
3. [Third thing]

• path/to/key/file.ts

  — [why it matters]

undefined

.claude/handoffs/[YYYY-MM-DD]-[brief-description].md

"I'll save this to

.claude/handoffs/[filename].md

. Want a different location?"

1. Decisions with reasoning — The "why" is often more valuable than the "what"
2. Code changes — File paths, what changed, the intent
3. Current progress — Where in the task we stopped
4. Next steps — Clear, actionable items to resume with
5. User context — Constraints, preferences, domain knowledge they shared

• Errors encountered — And how they were (or weren't) resolved
• Dead ends — Approaches tried that didn't work (saves re-exploration)
• Key files — Files to read to get back up to speed
• External dependencies — APIs, services, tools involved

• Verbose tool output (file listings, grep results)
• Intermediate reasoning that reached conclusions
• Repeated similar operations
• Information that's obvious from the code

• Bullet points — Scannable over narrative
• File paths —

  src/foo.ts:42

  not "that function"
• Checkboxes for actions —

  - [ ]

  for next steps and open questions
• Specifics — "Added retry logic to fetchUser()" not "made improvements"

1. Could a fresh Claude pick up from this? — Enough context to continue?
2. Are decisions traceable? — Clear why things were decided?
3. Are next steps actionable? — Know exactly what to do first?
4. Is code work clear? — Know which files matter?

1. Share the handoff file at session start
2. Say "Resume from this handoff: [paste or path]"
3. Reference it with @ mention if supported

• JWT with RS256 — Stateless auth, works with distributed setup
• Redis for refresh tokens — Need revocation capability
• 15-min access token expiry — Balance security/UX for mobile app

• src/auth/jwt.ts

  — Token generation and validation logic

• src/middleware/auth.ts

  — Request authentication middleware

• src/routes/auth.ts

  — Login/logout endpoints

• config/keys/

  — RSA key pair storage

config/keys/

• Automatic vs opt-in refresh token rotation?
• Rate limit for login attempts? (User mentioned 10k DAU)

• Client is a mobile app - tokens need offline capability
• User has 10k daily active users - scale matters
• Using PostgreSQL for user storage
• User prefers explicit error messages over generic ones

1. Implement

   /auth/refresh

   endpoint
2. Add rate limiting to

   /auth/login

3. Write tests for token expiry edge cases
4. Update API docs with auth flow

• src/auth/jwt.ts

  — Core token logic

• src/routes/auth.ts

  — Current endpoint implementation

undefined

• Ask what matters to the user before generating
• Decisions need reasoning — capture the "why"
• File paths anchor the work — always include them
• Next steps should be immediately actionable
• Better slightly longer and useful than short and vague