handoff-cortana — the session, written down
Produce a single, self-contained Markdown handoff document that lets the next
worker (human or AI) resume exactly where this session left off — with the
same understanding of what is done, what remains, why choices were made, and what
to do next. The output must prevent loss of plan or intent.
Prime directive: verify, don't narrate
A handoff that just recounts the chat is dangerous — the chat contains intentions,
abandoned ideas, and claims that may not match reality. Ground every
"done" against the repo. Before writing a status, confirm it:
git log --oneline -20 and git status --short — what actually landed vs. what
is uncommitted/dirty vs. only discussed.
- Read/
ls/grep the files a claim depends on — does the module/route/setting
actually exist? (Absence of evidence ≠ done.)
- Run the tests that would prove a claim; note pass/fail. A test file that
exists is not a test that passed — locating one earns CLAIMED, never
DONE (verified), and a test that skips, or asserts nothing that could
fail, proves nothing however green it prints. If you can't run them, say so —
never imply verification you didn't do.
Classify every item as one of: DONE (verified), CLAIMED (asserted in chat
but not confirmed in repo), IN-PROGRESS (partial / uncommitted), or
NOT STARTED. Never collapse CLAIMED into DONE.
Method
- Reconstruct the goal. Re-read the session from the top. State the original
objective and any scope changes in the user's own terms. Distinguish the
mission (why) from the tasks (what).
- Inventory the work. List everything attempted. For each, assign a status
from the four above with evidence (commit hash, file path:line, test name,
or "asserted in chat, unverified").
- Capture the reasoning. For every non-obvious decision: what was chosen,
what was rejected, and why. This is what prevents the next worker from
re-litigating settled questions or repeating dead ends. Pull rationale out of
the conversation — it is the most perishable, highest-value content.
- Surface the constraints & gotchas. Environment quirks, air-gap/offline
limits, credentials, flaky steps, "do not re-fix this" traps (check the repo docs
and whichever instruction file this host loads — CLAUDE.md, AGENTS.md,
SYSTEM.md). These cost the next worker hours if lost.
- Define the resume path. The exact next 1–3 actions, the first commands to
run to get oriented, and the branch/PR state. Be concrete enough that someone
can start in under five minutes.
- List open questions. Anything awaiting a user decision, unknowns, or risks.
Writing the document
Fill in template.md (in this skill's directory). Read it and follow its
structure and section-by-section guidance. Rules for the output:
- Self-contained. The reader has not seen this chat. Spell out acronyms,
link file paths as
path:line, quote the relevant commit messages. Do not write
"as discussed above" — there is no above.
- Evidence over assertion. Prefer "
geo/mosaic_qa.py — ABSENT (grep returned
0 matches)" to "QA judge not done".
- Ruthlessly current. If the plan changed mid-session, document the final
plan and note what was superseded, so nobody follows a stale branch of thought.
- Depth where it matters, brevity where it doesn't. In-depth on decisions,
rationale, gotchas, and resume steps; terse on boilerplate.
- No invention. If something is unknown, write "UNKNOWN — needs checking",
never a plausible guess. A confident wrong handoff is worse than an honest gap.
Output location & naming
Default to docs/handoffs/HANDOFF-<YYYY-MM-DD>-<short-topic-slug>.md (create the
folder if absent). If the repo has an obvious conventions dir (e.g.
docs/superpowers/), prefer matching it. If the user named a path or the
scratchpad, honor that. Confirm the location in your reply.
Optional args: treat any argument as the output path or a focus hint
(e.g. /handoff docs/notes/handoff.md or /handoff mosaic tracks).
Finish
After writing, reply with: the file path, a 3–5 line summary of the current state
it captured, and the single recommended next action. Do not commit or push
unless the user asks — the handoff is theirs to place.
1---2name: handoff-cortana3description: >-4 Use when the user asks to "hand off", "write a handoff", "create a handoff5 doc", "document where we are", "prepare for the next session/person", or6 wants a continuity/checkpoint summary of the current session — an in-depth,7 verified session-handoff document (a Markdown file) so a different person or8 AI can continue the work with zero loss of context, plan, or intent.9metadata:10 source: https://skillmd.com/skills/bodish-coder/handoff-cortana11---1213# handoff-cortana — the session, written down1415Produce a single, self-contained Markdown handoff document that lets the next16worker (human or AI) resume **exactly where this session left off** — with the17same understanding of what is done, what remains, why choices were made, and what18to do next. The output must prevent loss of plan or intent.1920## Prime directive: verify, don't narrate2122A handoff that just recounts the chat is dangerous — the chat contains intentions,23abandoned ideas, and claims that may not match reality. **Ground every24"done" against the repo.** Before writing a status, confirm it:2526- `git log --oneline -20` and `git status --short` — what actually landed vs. what27 is uncommitted/dirty vs. only discussed.28- Read/`ls`/`grep` the files a claim depends on — does the module/route/setting29 actually exist? (Absence of evidence ≠ done.)30- Run the tests that would prove a claim; note pass/fail. A test file that31 exists is not a test that passed — locating one earns **CLAIMED**, never32 **DONE (verified)**, and a test that skips, or asserts nothing that could33 fail, proves nothing however green it prints. If you can't run them, say so —34 never imply verification you didn't do.3536Classify every item as one of: **DONE (verified)**, **CLAIMED (asserted in chat37but not confirmed in repo)**, **IN-PROGRESS (partial / uncommitted)**, or38**NOT STARTED**. Never collapse CLAIMED into DONE.3940## Method41421. **Reconstruct the goal.** Re-read the session from the top. State the original43 objective and any scope changes in the user's own terms. Distinguish the44 *mission* (why) from the *tasks* (what).452. **Inventory the work.** List everything attempted. For each, assign a status46 from the four above **with evidence** (commit hash, file path:line, test name,47 or "asserted in chat, unverified").483. **Capture the reasoning.** For every non-obvious decision: what was chosen,49 what was rejected, and *why*. This is what prevents the next worker from50 re-litigating settled questions or repeating dead ends. Pull rationale out of51 the conversation — it is the most perishable, highest-value content.524. **Surface the constraints & gotchas.** Environment quirks, air-gap/offline53 limits, credentials, flaky steps, "do not re-fix this" traps (check the repo docs54 and whichever instruction file this host loads — CLAUDE.md, AGENTS.md,55 SYSTEM.md). These cost the next worker hours if lost.565. **Define the resume path.** The exact next 1–3 actions, the first commands to57 run to get oriented, and the branch/PR state. Be concrete enough that someone58 can start in under five minutes.596. **List open questions.** Anything awaiting a user decision, unknowns, or risks.6061## Writing the document6263Fill in `template.md` (in this skill's directory). Read it and follow its64structure and section-by-section guidance. Rules for the output:6566- **Self-contained.** The reader has *not* seen this chat. Spell out acronyms,67 link file paths as `path:line`, quote the relevant commit messages. Do not write68 "as discussed above" — there is no above.69- **Evidence over assertion.** Prefer "`geo/mosaic_qa.py` — ABSENT (grep returned70 0 matches)" to "QA judge not done".71- **Ruthlessly current.** If the plan changed mid-session, document the *final*72 plan and note what was superseded, so nobody follows a stale branch of thought.73- **Depth where it matters, brevity where it doesn't.** In-depth on decisions,74 rationale, gotchas, and resume steps; terse on boilerplate.75- **No invention.** If something is unknown, write "UNKNOWN — needs checking",76 never a plausible guess. A confident wrong handoff is worse than an honest gap.7778## Output location & naming7980Default to `docs/handoffs/HANDOFF-<YYYY-MM-DD>-<short-topic-slug>.md` (create the81folder if absent). If the repo has an obvious conventions dir (e.g.82`docs/superpowers/`), prefer matching it. If the user named a path or the83scratchpad, honor that. Confirm the location in your reply.8485Optional args: treat any argument as the output path or a focus hint86(e.g. `/handoff docs/notes/handoff.md` or `/handoff mosaic tracks`).8788## Finish8990After writing, reply with: the file path, a 3–5 line summary of the current state91it captured, and the single recommended next action. Do **not** commit or push92unless the user asks — the handoff is theirs to place.