Session Handoff

---
name: session-handoff
description: Compresses a long working session into a short handoff document a cold reader can continue from - goal and status, decisions with the reasoning that produced them, the exact next action, the dead ends already ruled out, and the commands that verify the current state. Use before context runs out, at the end of a work block, or when passing work to another session or person.
---

# Session Handoff

You are writing for someone with no memory of this session, who will start work in ten minutes. Everything they need is in the document; everything else is noise.

## Workflow

1. **Walk back through the session** and separate what was learned from what was merely said.
2. **State the goal in one sentence** and how much of it is done.
3. **Split the work into done, in progress, and not started**, with evidence for anything you claim is done.
4. **Record each decision with its reason.** A decision without its reason gets reversed by the next reader.
5. **Write the single next action**, concrete enough to begin without a decision.
6. **List the dead ends** - what was tried, what happened, why it was abandoned.
7. **Give the verification commands** and what a healthy result looks like.
8. **Collect the pointers**: branch, files with full paths, services, credentials location (never the credentials).

```text
Handoff checklist
[ ] Goal in one sentence
[ ] Status split into done / in progress / not started
[ ] Every "done" has evidence attached
[ ] Every decision has its reason
[ ] Next action is specific enough to start immediately
[ ] Dead ends recorded with what happened
[ ] Verification commands included, with expected output
[ ] File paths absolute, branch named, no secrets
```

## What to capture

**The goal and how far it got.** Not the history of how it got there.

**Decisions and their reasons.** "We stream the export rather than building it in memory, because a large tenant's report is around 900MB." Without the second half, the next session rewrites it as a simple in-memory build and rediscovers the limit in production.

**The real state of the code.** Which branch, which files, what works, what is half-written and will not compile, what is stubbed.

**The next action.** One thing, specific. "Wire the date-range picker in `reports.js:142` to the `from`/`to` query parameters the endpoint already accepts" - not "continue the filter work".

**Dead ends.** Everything tried that failed, and what the failure looked like. This is the section that saves the most time and is the first one people leave out.

**How to verify.** The commands that prove the state is what you say it is, and what output means healthy.

**Pointers.** Branch, absolute file paths, service URLs, ticket numbers, where credentials live.

## What to leave out

- The chronological story of the session. The reader wants the current state, not the journey.
- Anything already obvious from the code or the commit history.
- Options considered and rejected early, unless someone is likely to propose them again.
- Praise, apology, and the phrase "as discussed" - there is no shared discussion with a cold reader.
- Secrets, tokens, keys, connection strings with passwords in them. Say where they live instead.

## Document template

```markdown
# Handoff: <topic> - <date>

**Goal.** One sentence.

**Status.** <n> of <m> done. One line on where things stand.

## Done
- <thing> - evidence: <test, command output, or observed behaviour>

## In progress
- <thing> - exact current state, including anything that will not compile or run

## Decisions
- <decision> - because <reason>

## Next action
<One concrete step, with the file and line if it has one.>

## Watch out
- <dead end> - tried <what>, got <result>, abandoned because <reason>

## How to verify
- `<command>` - expect: <what a healthy result looks like>

## Pointers
- Branch: <name>
- Files: <absolute paths>
- Services / URLs / tickets: <list>
- Credentials: <where they live, never the values>
```

## Example

A compressed version of a real handoff, showing the density to aim for:

> **Goal.** Add CSV export to the reports page.
>
> **Status.** Backend done and tested; the date-range filter is not wired up.
>
> **Done.** `GET /api/reports/export` streams CSV - `pytest tests/api/test_export.py`
> passes, 6 tests, including a 200k-row streaming case.
>
> **In progress.** The export button posts the current filters, but `reports.js`
> sends `range: "last30"` while the endpoint expects `from` and `to` dates. The
> request 400s.
>
> **Decisions.** Stream row by row rather than building the file in memory,
> because the largest tenant's yearly report is roughly 900MB.
>
> **Next action.** In `reports.js:142`, convert the range selector value into
> `from`/`to` ISO dates before the request. `dateRangeToBounds()` in
> `utils/dates.js` already does this for the chart.
>
> **Watch out.** Tried returning the CSV as a single response body first; the
> worker was killed at 512MB on the tenant above. Do not go back to that shape.
> Also: the test database has three rows, so streaming is untested against real
> volume anywhere but staging.
>
> **How to verify.** `pytest tests/api/test_export.py -q` expects 6 passed. Then
> open `/reports`, pick any range, click Export - a file downloads today only if
> you set the dates by hand in the network tab.

Every line either tells the reader the state, stops them repeating a mistake, or tells them exactly where to type next.

## Rules

- Write for a reader with zero memory of this session. No "as discussed", no "the file we changed", no "that bug".
- Record why, not just what. An unexplained decision has a short life.
- Be specific: absolute paths, exact commands, branch names, line numbers where they help.
- Include what failed. A hidden dead end is a dead end the next session walks into.
- Attach evidence to every claim of "done". "Tests pass" with the command beats "should be working".
- Keep it scannable. A wall of prose is a handoff nobody reads.
- No secrets in the document. Name the vault, the environment file, or the person to ask.
- Prefer honest incompleteness. "I do not know why the staging build fails" is more useful than a guess presented as fact.

## Edge cases

- **The session achieved nothing.** Say so, and record what was ruled out. A session that eliminated three theories has real value if the theories are written down.
- **Handing to a person, not a session.** Add the context a colleague needs and a machine does not: who asked for this, what they are expecting, when, and who to ask about the ambiguous part.
- **The work is blocked.** Lead with the blocker, name who or what unblocks it, and describe what can be done in the meantime.
- **Half-written code that does not compile.** Say exactly which file and what state it is in. The next reader must not discover this by running the build.
- **You are close to the end of context.** Write the handoff before you finish the last task, not after. An unwritten handoff is worth nothing.
- **A decision was the user's, not yours.** Mark it as theirs. The next session should not reverse it unilaterally.
- **Multiple threads of work.** One handoff per thread if they are truly independent. If they interact, write one document and say how they touch.

## Files

- `references/examples.md` - two complete handoff documents at full length, one mid-feature and one for a paused investigation, plus a weak handoff rewritten line by line into a strong one. Read it to calibrate how much detail each section needs.

# Worked handoffs

Two complete documents at the length they should actually be, then a weak handoff rewritten line by line. The third one is where most of the learning is: the weak version reads fine until you try to use it.

## Contents

- [Handoff 1: mid-feature, work continues tomorrow](#handoff-1-mid-feature-work-continues-tomorrow)
- [Handoff 2: a paused investigation](#handoff-2-a-paused-investigation)
- [Handoff 3: weak version rewritten](#handoff-3-weak-version-rewritten)
- [What the strong ones do](#what-the-strong-ones-do)

---

## Handoff 1: mid-feature, work continues tomorrow

# Handoff: CSV export for reports - 12 June

**Goal.** Let a user download the current reports view as a CSV file.

**Status.** Backend complete and tested. Front end sends the wrong parameter shape, so the button currently returns a 400.

## Done

- `GET /api/reports/export` streams CSV with the same filters the HTML view accepts.
  Evidence: `pytest tests/api/test_export.py -q` - 6 passed, including a 200,000-row
  case that holds memory under 60MB.
- Column set agreed with finance and frozen in `exports/columns.py`. Evidence: the
  list is asserted in `test_export_columns_match_spec`.

## In progress

- The Export button in `src/pages/reports.js` posts `{ range: "last30" }`. The
  endpoint expects `from` and `to` as ISO dates. Every click 400s with
  `{"error": "from is required"}`. Nothing is half-written; it is a one-place
  mismatch.

## Decisions

- **Stream the response row by row** rather than building the file in memory,
  because the largest tenant's yearly report is roughly 900MB and the worker is
  capped at 512MB.
- **CSV only, no Excel format**, because finance imports into a system that reads
  CSV and adding a second format doubles the column-mapping tests. Revisit only if
  they ask.
- **No email delivery.** The user waits for the download. Discussed with the
  requester on 11 June; they preferred the simpler flow.

## Next action

In `src/pages/reports.js:142`, convert the range selector value into `from` and
`to` ISO dates before building the request. `dateRangeToBounds()` in
`src/utils/dates.js` already does exactly this for the chart - reuse it rather
than writing a second conversion.

## Watch out

- **Do not return the CSV as a single response body.** That was the first shape;
  the worker was OOM-killed at 512MB on the tenant above. The streaming shape is
  the fix, not a preference.
- The test database has three rows, so streaming is only genuinely exercised on
  staging. `scripts/seed_large.py` will generate 200k rows locally if needed.
- `test_export_columns_match_spec` is deliberately strict. If it fails after a
  column change, update the spec file rather than loosening the assertion.

## How to verify

- `pytest tests/api/test_export.py -q` - expect 6 passed.
- `curl -s "localhost:8000/api/reports/export?from=2026-05-01&to=2026-05-31" | head -3`
  - expect a header row plus two data rows.
- Open `/reports`, click Export - currently expected to fail with a 400 until the
  next action is done.

## Pointers

- Branch: `feat/csv-export`, based on `main` at `a41f2c9`.
- Files: `api/exports/routes.py`, `api/exports/columns.py`,
  `src/pages/reports.js`, `src/utils/dates.js`.
- Ticket: REP-311. Requester: the finance lead who asked on 11 June.
- Credentials: staging database URL is in the team vault under `staging/db`; it is
  not in any environment file in the repo.

---

## Handoff 2: a paused investigation

# Handoff: intermittent 502s on the checkout endpoint - 3 April

**Goal.** Find why roughly 1 in 400 checkout requests returns a 502.

**Status.** Not fixed. Three theories eliminated, one theory live and testable. No
code changed.

## Done

- Confirmed the 502s are real and not a monitoring artefact: they appear in both
  the load balancer log and the client-side error reports, with matching request
  ids.
- Narrowed to a single service. All failures come from `checkout-api`, never from
  `payments` or `catalog`.
- Established a rough rate: 1 in 380 requests over a 24-hour window, with no daily
  pattern.

## In progress

Nothing is running. The investigation is paused, not blocked.

## Decisions

- **Not adding a retry at the load balancer yet**, because a retry on a checkout
  request risks a duplicate charge and would also hide the signal we need.

## Next action

Test the live theory: the service is being recycled while requests are in flight.
Compare the timestamps of the 502s against the pod restart events for the same
window. `kubectl get events -n prod --field-selector reason=Killing` covers the
last hour; anything older needs the log archive.

## Watch out

- **Not the database.** Connection pool metrics are flat across every failure -
  no exhaustion, no spike in wait time. Checked twice, once per day.
- **Not the payment provider.** Their status page is clean for the window and
  their own dashboard shows every one of our requests succeeding, including the
  ones we returned a 502 for. That is a strong hint the failure is after their
  response comes back.
- **Not a bad deploy.** The rate is identical either side of the last three
  releases.
- Reproducing locally has failed after two hours of trying. Do not spend more time
  on that route; the evidence is in production.

## How to verify

- `scripts/count_502s.sh --hours 24` - currently reports around 240 out of ~91,000.
- Grafana dashboard "checkout latency" - the 502s show as gaps, not as slow
  requests, which is what pointed away from timeouts.

## Pointers

- No branch. Nothing has been changed.
- Log archive: the observability bucket, prefix `checkout-api/2026-04/`.
- Ticket: INF-882, with the three eliminated theories already written into the
  comments.

---

## Handoff 3: weak version rewritten

### What was written

> Worked on the auth refactor today. Made good progress - most of it is done. Ran
> into some issues with the session handling as discussed, but found a workaround.
> The tests are mostly passing except for a couple that were already flaky. Next
> up is finishing the middleware piece. Let me know if you have questions.

Every sentence sounds like information and none of it survives contact with a cold
reader. "Most of it", "some issues", "a workaround", "mostly passing", "a couple",
"the middleware piece", "as discussed" - the reader cannot act on a single one, and
the author is not available to ask.

### The rewrite

> **Goal.** Move authentication from the per-route decorator to a single
> middleware.
>
> **Status.** 9 of 12 routes migrated. The 3 admin routes are untouched.
>
> **Done.** The 9 public routes now authenticate in `middleware/auth.py`. Evidence:
> `pytest tests/routes -q` - 44 passed. Their decorators are removed.
>
> **In progress.** `middleware/auth.py:61` handles bearer tokens but not the legacy
> session cookie, so the 3 admin routes still use the old decorator and must not be
> migrated until that lands.
>
> **Decisions.** Kept the legacy cookie path alive rather than forcing a re-login
> for admins, because the admin session store has no expiry data and we cannot tell
> who would be logged out.
>
> **Next action.** Add cookie handling to `middleware/auth.py:61`, reusing
> `legacy_session_user()` from `auth/legacy.py`, which the old decorator already
> calls.
>
> **Watch out.** Two tests in `tests/test_login.py` fail intermittently -
> `test_concurrent_login` and `test_refresh_race`. They failed on `main` before
> this work started; they are not caused by the refactor. Ordering-related.
>
> **How to verify.** `pytest tests/routes -q` - expect 44 passed.
> `pytest tests/test_login.py -q` - expect 11 passed, 2 intermittent failures.
>
> **Pointers.** Branch `refactor/auth-middleware`. Files: `middleware/auth.py`,
> `auth/legacy.py`, `tests/routes/`.

The rewrite is four times longer and the first version was unusable, so the
comparison is not really about length. Every vague phrase became a number, a file,
or a command.

---

## What the strong ones do

1. The status is a count, not an adjective. "9 of 12 routes" cannot be misread; "most of it" can.
2. Everything claimed done drags its evidence along - a command and its expected output.
3. Decisions carry the constraint that produced them, so the next reader knows what would have to change for the decision to change.
4. The next action names a file, a line, and often the existing helper to reuse. The reader starts typing rather than deciding.
5. Dead ends are stated as instructions ("do not go back to that shape"), not as history.
6. Known-flaky tests are separated from tests this work broke. Without that line, the next session spends an hour on a pre-existing problem.
7. Credentials are located, never quoted.