Handoff

---
name: handoff
description: Generate a Markdown handoff document summarizing the current conversation so another agent (Claude, Codex, opencode, pi, ampcode, Cursor, or a fresh session) can resume without re-deriving context. Produces docs/<slug>-handoff.md. Invoke explicitly when a session is near its context limit.
disable-model-invocation: true
allowed-tools:
  - Bash(ls *)
  - Bash(mkdir *)
  - Bash(git rev-parse *)
  - Bash(git symbolic-ref *)
  - Write
---

# handoff

This skill runs **when context is nearly exhausted**. Budget is the constraint. Draft from what's already in conversation context — do not re-read files, do not grep, do not ask interview questions, do not run a self-check pass. One `Write` call is the goal.

## Output path

`docs/<slug>-handoff.md` where `<slug>` is a 2–3 word kebab-case identifier derived from the session's main agenda (or the user's freeform argument to the slash command, if given).

- Lowercase, alphanumeric + hyphens only.
- If the file exists, append `-2`, `-3`, … — never clobber.
- `mkdir -p docs` if needed.

## Audience

Another LLM coding agent with Read/Write/Bash but **zero prior context**. Write for them: concrete paths, exact commands, exact error strings. No prose pleasantries, no recap of the dialogue.

## Sections (in order)

Include only sections with real content. Omit or write `None this session.` for empty ones — never pad.

1. **Header** — one-line crux (what this session was about), branch, date, working dir.
2. **Agenda** — 2–4 sentences on the goal.
3. **Files read** — bullet list: path + half-sentence on why it mattered.
4. **Files written / edited** — table: `File | Change`.
5. **Bugs found** — symptom + root cause (if known) + file:line.
6. **Fixes made** — what was broken + the fix + where.
7. **Skills used** — `/ank:<skill>` invocations + outcome. Omit if none.
8. **Links / references** — URLs, issue/PR numbers, doc paths.
9. **Key decisions** — non-obvious choices + *why*. Prevents re-litigation.
10. **Current state** — what works, what's half-done, what's untested. Quote actual build/test output if you ran any; say so if you didn't.
11. **Open questions / not done** — explicit gaps, deferred items.
12. **Next steps** — concrete, ordered. Each item must be actionable without a clarifying question (e.g. "read `frontend/lib/auth.ts` and trace `refreshToken()`" — not "figure out auth"). Write this last.

**Optional** (include only if substantial and quick to produce): a fenced ASCII layout/architecture diagram, key types/state shape, or API surface touched.

Shape: tables for file lists, fenced ASCII for diagrams, short headers, no filler prose.

## Constraints

- **Markdown only.** No HTML, images, or external assets.
- **No invented paths, line numbers, commits, or counts.** If unsure, omit — don't verify, you don't have the budget. The receiving agent will grep.
- **No transcript dump.** Distill the work, not the dialogue.
- **No interview.** Use the user's slash-command argument if given; otherwise derive the slug and crux yourself.
- **No self-check pass.** Get the file written.
- **Don't run builds, tests, or migrations** to populate the doc. Report state as observed.