ops-handoff

Capture the state of the current session into a dated handoff note, so a new session resumes without re-discovering everything.

Positioning

• A handoff is a task-in-progress transfer: ephemeral and dated. It is NOT long-term memory.
• Long-term, stable facts belong in your persistent memory file. Do not duplicate them here.
• A handoff complements memory: it captures the volatile working state that memory deliberately omits.

Where to save

Save to: ~/handoffs/YYYY-MM-DD-HHmm-[subject].md

• subject is a short kebab-case slug of the current task (e.g. payments-refactor).
• Save in a folder that persists and syncs across devices (a notes vault, a synced directory), not OS temp.
• Create the folder if missing: mkdir -p ~/handoffs.
• Generate the timestamp with date "+%Y-%m-%d-%H%M".

Core principle: reference, never duplicate

If information already lives in another artefact (note, source file, PR, URL), link to it by path or URL. Do not copy its content into the handoff. The handoff is an index of state, not a snapshot of everything.

What to capture

Write these sections in order. Keep each tight.

1. Goal — the task in progress, in one or two sentences.
2. Decisions made — choices locked in this session, with the reasoning if non-obvious.
3. Current state — where things stand right now (what works, what is half-done).
4. Next steps — the concrete actions the next session should take, ordered.
5. Files & notes touched — absolute paths / links / URLs. Do not paste their contents.
6. Open questions — unresolved points, blockers, things needing the user's input.
7. Suggested skills — which skills to invoke next session to continue (e.g. /product-prd-write, /skill-create). List only relevant ones.

Redaction

Never copy secrets, credentials, tokens, or private keys into the handoff. Reference where they live instead (e.g. "API key in the password manager / .env"). If a touched file contains secrets, link the file but redact the values.

Template

# Handoff — [subject] — YYYY-MM-DD HHmm

## Goal
...

## Decisions made
- ...

## Current state
...

## Next steps
1. ...

## Files & notes touched
- `/abs/path/to/file` — what changed / why it matters
- [link or note reference]

## Open questions
- ...

## Suggested skills
- `/skill-name` — why

After writing

Print the absolute path of the saved handoff so the user can open or share it. Do not summarise the whole content back; the file is the artefact.