handoff

handoff

Turn "coordinate a handoff" into three artifacts: a status doc committed to pulp-planning main, a simple goal prompt that links it, and a list of open items for the next session to track. The point is a fresh session — often on a different machine, with none of this conversation's context — can start cold and finish the work.

Keep the goal short (one or two sentences + a link + the issue numbers). Put all the detail in the doc. A goal the user pastes should fit in a glance; the doc is where the elaboration lives.

Carry the original ask forward faithfully — this is the #1 job. A handoff exists to hand off the goal the user actually gave, not a reconstruction of it. A handoff most often happens mid-project, and the failure mode is quietly narrowing the goal to "whatever's left in flight," or paraphrasing it into something subtly different from what was asked. Guard against both:

• Rediscover the last-known goal before writing anything. Prefer the goal as it was captured — the user's own words. Look, in order, for: a persisted goal record (a planning/*-goal.md or the "original ask" block of a prior handoff doc), the standing objective the session was given (e.g. a Claude Code /goal or the opening prompt), and the earliest user messages that framed the project. Quote it; don't restyle it.
• If it was never captured, reconstruct it faithfully and then persist it in the doc's "original ask" block, marked as a reconstruction — so the next handoff rediscovers a real record instead of reconstructing again. Each handoff should make the goal more durable, not drift it further.
• Fidelity over polish — no invented scope. Do not add scope, sharpen vague asks into crisp requirements, or merge in your own opinion of what "should" be done. If the ask was "build this planning file until it's all done," the handoff says exactly that — not a reworded, expanded brief. A handoff is translation, not a fresh review: never turn "carry this plan to the new machine" into "re-plan the project." When unsure whether a requirement was in the ask, mark it inferred, not stated.
• Source from the original documents. Point at the plan/spec/issue/goal the user actually wrote and quote it; do not substitute your own summary as the record. If the original lives somewhere ephemeral (a scratch plan, in-session goal text), copy it verbatim into the durable goal record so it survives.
• Capture honest evolution, kept distinct. Goals do grow — the user adds scope as work proceeds. Capture those additions too, but separate "original ask" from "added later" (with when/where each came from) so the record stays honest and no one can't tell invented scope from real scope. Only include an addition the user actually made; never one you think would be good.
• The remaining tasks/issues are how the objective is tracked, never a redefinition of it. "Do all of X; here's the part still undone" — never "do the three tickets that happen to be open."

Capture the goal at ask-time (the durable fix). The reliable way to hand off a goal is to have written it down when it was given. When a user sets a project goal or standing objective, persist it verbatim to a durable, agent-neutral, machine-portable place (a planning goal file) so any later session — Claude or Codex, any machine — can rediscover the last known goal without depending on one CLI's memory or slash-command state. The handoff is the fallback when that wasn't done; the capture is the fix.

Reference, don't duplicate. The doc is a map to the work, not a copy of it. Anything already captured in another artifact — a plan/spec, an ADR, a GitHub issue, a commit message, a diff, an existing skill — gets linked by path or URL, never re-pasted. Re-leverage the docs the work already produced. A handoff that restates a tracking issue's item list drifts from it the moment the issue is edited; one that links the issue stays correct for free. The doc's own content is only what exists nowhere else: the current honest status, which tracker to drive vs monitor, the working pattern, and the traps this work paid for.