OPS-03 · SEC. 03 Operations & DevOps

Session Handoff Note for a Different Session or Teammate

Write a handoff so the next session or teammate starts working in minutes, not re-explaining.

FORMAT: workflow
DIFFICULTY: intermediate
TIME: 8 min
TOOLS: universal
MODELS: any
COPIES: 0 so far

When to use this

You're stopping mid-task, work isn't finished, and either you in a new session or a teammate needs to pick it up cold. A vague commit message isn't enough context to continue safely.

The pattern

Pastes as plain text

I'm stopping mid-task and need a handoff note so the next session or a
teammate can pick this up cold, with zero re-explaining. Do the following:

1. Run `git status` and `git branch --show-current`. Note the branch name and
   whether there are uncommitted changes.
2. Do not commit, stash, discard, or push anything as part of this handoff.
   Note which changes are safe to keep, experimental, or incomplete, and ask
   me separately before any repository mutation.
3. Write a handoff note with these exact sections:
   - Goal: what this branch/task is trying to accomplish, one sentence.
   - Done: bullet list of what's working and verified.
   - In progress: what's partially done and exactly where it's incomplete
     (file + function name, not just "the API part").
   - Next step: the single next action to take, specific enough to start
     coding immediately.
   - Known issues: anything broken, flaky, or deliberately left unfinished.
   - How to verify: the exact command(s) to run to confirm current state
     (tests, build, dev server).
4. Output the note as plain text in the response. Do not save it as a file
   unless I explicitly ask.

Real example output

Branch: feature/csv-export (pushed, working tree clean, 1 stash: "wip-streaming-attempt")

Goal: Add CSV export for the orders table with streaming for large datasets.

Done:
- Basic CSV export endpoint at POST /api/orders/export (non-streaming, works up to ~5k rows)
- Column selection UI in ExportDialog.tsx
- Tests for the non-streaming path pass

In progress:
- Streaming export using ReadableStream in src/api/orders/export/route.ts,
  stalls after ~10k rows, likely backpressure not handled in the chunk writer
  (see writeChunk() around line 88). Stashed as "wip-streaming-attempt", not
  committed because it breaks the non-streaming fallback.

Next step: Pop the stash, fix backpressure handling in writeChunk(), test
with the 50k-row fixture in test/fixtures/orders-large.csv.

Known issues: Non-streaming export has no row limit guard, will OOM above
~20k rows if streaming isn't finished by launch.

How to verify: npm test -- export, then npm run dev and hit
POST /api/orders/export with test/fixtures/orders-small.csv.

Why it works

Handoffs fail when the next person has to reverse-engineer state from a diff and a vague commit message. Naming the exact file, function, and failure mode turns "figure out where I left off" into "start at line 88."

Related patterns

OPS-11Project State Handoff File (Phase, Environment, Decisions)Maintain one HANDOFF.md that survives across sessions: phase, ports, decisions log.ENG-15Repomix Context HandoffPack the full codebase into one file before closing a session, so the next agent inherits real code.OPS-01End-of-Session Git ChecklistRun before closing any coding session so nothing sits uncommitted overnight.