Pablo Fernandez

Have a coding agent write handoff notes before you stop

End an agent session with handoff notes a fresh session or teammate can resume from: state, decisions, dead ends, exact failures and next steps.

At a glance

Best for: Claude Code, Codex and Cursor users whose sessions run out of context, get interrupted, or pass work between people or tools.
Tested on: Claude · Opus 5.5
You fill in: handoff_pathsession
You get: Handoff: Jest → Vitest migration Goal Move the whole monorepo's unit tests from Jest to Vitest. State [x] packages/utils converted [x] packages/api… (full result below)

Prompt

We're stopping here. Write handoff notes so a fresh agent session, or a teammate, can continue without re-reading this conversation. Save them to {{handoff_path}} if you can write files; otherwise print them.

Session context (if this isn't the session you're in): {{session}}

Structure:

1. Goal: the original task, in one sentence.

1. State: a checklist of done, in progress and not started. For in-progress items, give the exact file and function.

1. Decisions and why, including options rejected. This is the part that gets lost.

1. Dead ends: what was tried and what happened, so nobody tries it again.

1. Current failures: failing tests or errors, verbatim.

1. Next 3 steps, concrete enough to start without thinking.

1. How to get back to this state: branch, setup, and the commands to run the relevant tests.

Only include what's true. If you're not sure something was finished, mark it "unverified". Under 400 words.

Fill in

{{handoff_path}}: Where the notes should be savede.g. docs/handoff/vitest-migration.md
{{session}}: The session history, or your rough notes and terminal output if you're moving between toolse.g. Branch chore/vitest-migration; api and utils converted; 2 failing tests...

Example input

handoff_path: docs/handoff/vitest-migration.md
session:
```
- branch chore/vitest-migration, goal: move whole monorepo from Jest to Vitest
- done: packages/utils, packages/api converted. packages/web still on jest
- coverage: tried @vitest/coverage-istanbul, OOM in CI. switched to @vitest/coverage-v8, works locally, not run in CI yet
- replaced jest.mock -> vi.mock. 3 tests in api used jest.requireActual -> vi.importActual (it's async, made mock factories async)
- tried vitest.workspace.ts -> deprecation warning, used test.projects in root vitest.config.ts instead
- web uses jsdom + testing-library, setupTests.ts imports '@testing-library/jest-dom' -> needs '@testing-library/jest-dom/vitest'
- pnpm --filter api test:
  FAIL src/routes/orders.test.ts > creates order
    TypeError: vi.mocked(...).mockResolvedValue is not a function
  FAIL src/lib/time.test.ts > formats IST date
    AssertionError: expected '24 Sept 2026' to be '24 Sep 2026'
- haven't touched .github/workflows/test.yml
```

9950

Generated Outputs (1)

3 hours ago

Claude

Opus 5.5

3 hours ago

Generated Output

Handoff: Jest → Vitest migration

1. Goal
Move the whole monorepo's unit tests from Jest to Vitest.

2. State

• [x] packages/utils converted

• [x] packages/api converted (2 failing tests, see section 5)

• [ ] packages/web: still on Jest, not started

• [ ] .github/workflows/test.yml: not updated

• [ ] Coverage with @vitest/coverage-v8: works locally; unverified in CI

3. Decisions

• Coverage provider is @vitest/coverage-v8. coverage-istanbul ran out of memory in CI.

• Projects are configured with test.projects in the root vitest.config.ts, not a vitest.workspace.ts file, which gave a deprecation warning.

• jest.requireActual became vi.importActual. It's async, so the three affected mock factories in packages/api are now async.

4. Dead ends

• vitest.workspace.ts: deprecated, so don't reintroduce it.

• @vitest/coverage-istanbul: OOM in CI.

5. Current failures (pnpm --filter api test)
`
FAIL src/routes/orders.test.ts > creates order
TypeError: vi.mocked(...).mockResolvedValue is not a function
FAIL src/lib/time.test.ts > formats IST date
AssertionError: expected '24 Sept 2026' to be '24 Sep 2026'
`
Causes not investigated. Leads, both unverified:

• orders.test.ts: this error usually means the module isn't actually mocked, so vi.mocked returns the real function. Check that the vi.mock() path matches the import path exactly.

• time.test.ts: 'Sept' vs 'Sep' is Intl output for the en-GB locale, which varies with the ICU data in the Node build. Check whether Jest ran on a different Node version, or assert on a locale-independent format.

6. Next 3 steps

1. Fix src/routes/orders.test.ts: compare the vi.mock() specifier with the import in src/routes/orders.ts.

1. Fix src/lib/time.test.ts once the Node/ICU question is answered.

1. Start packages/web: in setupTests.ts, change the import to @testing-library/jest-dom/vitest, set environment: "jsdom" for the web project, and run it.

7. Get back to this state
`bash
git checkout chore/vitest-migration
pnpm install
pnpm --filter api test # expect the 2 failures above
pnpm --filter utils test # expect green (unverified since last change)
node --version # record this for the time.test.ts question
`

Why it works

Decisions and why, including options rejected is the section that saves the most time. Without it, the next session reintroduces the deprecated workspace file or retries Istanbul. Asking for failures verbatim preserves the exact error text a new session needs for searching and diagnosis. The "unverified" label stops the notes claiming things are done when they weren't checked, the most common way handoffs mislead. Next steps concrete enough to start without thinking mean the next session can begin work straight away instead of spending its first stretch rediscovering context.

When not to use it

It's not worth it for short sessions you'll resume within the hour. Your tool's resume or continue feature keeps the full context anyway. Notes written by the agent are only as reliable as its memory of the session. After long sessions, compare them against git log and a fresh test run before trusting them. Don't commit notes that contain secrets or customer data from logs.

Comments (0)

No comments yet. Be the first to share your thoughts!