Next action
One instruction, not a summary
The receiver should not have to derive what to do from a wall of state. The first thing in the artifact is the single next move, and whether anything blocks it.
The artifact
What a handoff actually looks like.
Every competitor built a place to store context and a way to query it. That is a database posture. The job to be done is a transfer.
handoff/payments-migration.md
# Handoff: payments-migration
## Next action
Wire the retry path in charges/worker.rb to the new idempotency key. Nothing else is blocking.
## State
Ledger writes are cut over and green in staging. Read path is still dual-reading.
Rollback flag payments.v2_reads is live and tested.
## Constraints (do not violate)
- -[human · confirmed 2026-07-14] No downtime window. Cutover must be online.
- -[human · confirmed 2026-07-02] Idempotency keys are namespaced per merchant, not global.
- -[agent · claude-code · unconfirmed] Stripe webhook ordering is not guaranteed; do not rely on it.
## Decisions and why
- -[2026-07-11 · human] Postgres advisory locks over Redis for the cutover lock.Rationale: we already page on Postgres; adding a Redis dependency to the critical path was rejected.
- -[2026-07-19 · agent, human-confirmed] Dual-read window set to 14 days, not 7.Rationale: month-end reconciliation needs a full cycle inside the window.
## Open questions
- - [ ]Who owns the backfill for pre-2024 charges? Unassigned since 2026-07-08.
- - [ ]Do we need the dual-read window extended for EU entities? Raised by agent, unverified.
## Superseded recently (do not re-propose)
- -~~Redis-based cutover lock~~ superseded 2026-07-11, see decision above.
- -~~7-day dual-read window~~ superseded 2026-07-19.
## Artifacts
- -PR #2841 (ledger cutover)
- -ADR-017
Rendered markdown, frozen at creation, plus a live link.
Section by section
Why each block is in there.
Constraints
Marked by who set them
A human-confirmed constraint and an unconfirmed agent assertion are not the same object and must not look the same. Human items carry the accent; agent items are muted until a human confirms them.
Decisions
Carrying the rationale
A decision without its reasoning gets re-litigated the moment someone new arrives. Every decision states why, and what alternative it beat.
Open questions
Unresolved, and visibly so
Including who owns them and how long they have been sitting. An open question with no owner since three weeks ago is information about the project, not just about the task.
Superseded
The section nobody else produces
What was tried, rejected, and must not be proposed again. This is the highest-value block in the artifact and the reason a fresh agent does not walk straight back into the approach the team already ruled out.
Artifacts
Pointers to the real work
PRs, ADRs, tickets. The handoff does not duplicate them, it locates them.
The thesis
“The unit of value is not memory. It is the handoff.”
Work stops with one actor and resumes with another: the same human tomorrow, a different human next week, a different agent on the next task. The thing that should exist is an artifact produced at the moment of stopping and consumed at the moment of resuming.
It also has to survive crossing tools. If it only works inside one vendor's client, it is not a handoff.