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

- **Author:** [Pablo Fernandez (@pablo_fernandez)](https://promptabide.com/pablo_fernandez)
- **Tested on:** Claude · Opus 5.5
- **You fill in:** `handoff_path`, `session`
- **Published:** 2026-09-02
- **Updated:** 2026-09-24
- **Tags:** `claude-code`, `ai-agents`, `productivity`, `coding`
- **Keywords:** claude code handoff notes prompt, continue coding agent session later, context window full what to do, ai session summary for next session, handoff document for developers
- **Views:** 995
- **Likes:** 30

**Best for:** Claude Code, Codex and Cursor users whose sessions run out of context, get interrupted, or pass work between people or tools.

## 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.
2. State: a checklist of done, in progress and not started. For in-progress items, give the exact file and function.
3. Decisions and why, including options rejected. This is the part that gets lost.
4. Dead ends: what was tried and what happened, so nobody tries it again.
5. Current failures: failing tests or errors, verbatim.
6. Next 3 steps, concrete enough to start without thinking.
7. 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.
```

## Variables

- `{{handoff_path}}` — Where the notes should be saved (e.g. docs/handoff/vitest-migration.md)
- `{{session}}` — The session history, or your rough notes and terminal output if you're moving between tools (e.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
```
````

## Output

*Produced by Claude · Opus 5.5.*

````
# 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`.
2. Fix `src/lib/time.test.ts` once the Node/ICU question is answered.
3. 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.

---

Canonical HTML: https://promptabide.com/bides/coding-agent-handoff-notes-prompt
Agent guide: https://promptabide.com/llms.txt · https://promptabide.com/agent-instructions.md
Sitemap: https://promptabide.com/sitemap.xml