handoff

Handoff

Write a markdown brief under ~/tmp/ that a fresh agent — with no memory of this conversation — can read once and execute. The receiving agent has full tools (file access, shell, web) but zero context: assume it has never seen the repo, the user, or the prior discussion.

Quick start

1. Pick a short kebab-case slug for the task (fix-auth-redirect, migrate-jobs-table).
2. Write the file to ~/tmp/handoff-YYYY-MM-DD-{slug}.md using the template below.
3. Tell the user the path. They'll point the next agent at it (e.g. "read ~/tmp/handoff-...md and execute it").

Filename convention

~/tmp/handoff-{YYYY-MM-DD}-{slug}.md

Date first so listings sort chronologically. Use today's date (from system context), not a guess.

Template

# Handoff: {one-line title}

**Written:** {YYYY-MM-DD} by {originating agent / user}
**Repo / cwd:** {absolute path}
**Branch:** {branch name, or "none — not a git repo"}

## Goal & acceptance criteria

{2–4 sentences: what outcome the user wants. Then a checklist of concrete, verifiable
conditions that mean "done". The receiving agent will treat this as the contract.}

- [ ] {criterion 1 — observable, testable}
- [ ] {criterion 2}
- [ ] {criterion 3}

## Context & current state

{Why this work matters. Prior decisions already made (and why). Anything tried that
didn't work. Relevant files with absolute paths and line numbers. Links to PRs, issues,
docs. What's already committed vs. uncommitted on the branch.}

Key files:
- `{absolute/path/to/file.ext}:{line}` — {what's there, why it matters}
- ...

## Constraints & verification

**Must not:**
- {hard constraints: don't touch X, don't break Y, don't push to main, etc.}

**Conventions to follow:**
- {repo conventions, code style, commit message format, branching flow}

**Verify by running:**
```bash
{exact commands the receiving agent should run to confirm the work is correct}

Suggested plan

{Optional. Include only if you have enough context to propose concrete next steps. Mark it as a suggestion, not a mandate — the receiving agent should re-evaluate once they've read the code. Omit this section entirely if you'd just be guessing.}

1. {step}
2. {step}
3. {step}

## Writing a good handoff

The receiving agent **cannot ask clarifying questions** (or if it can, it costs a round-trip with the user). Front-load everything:

- **Absolute paths, not relative.** `$HOME/src/foo/bar.py:42`, not `bar.py`.
- **Exact commands.** Paste the command the agent should run, with flags. Don't write "run the tests" — write `uv run pytest tests/test_auth.py -k redirect`.
- **Name the branch.** If work is in progress on a feature branch, say so. If the agent should create one, say what to call it.
- **Quote, don't summarise, the user's actual ask.** A direct quote of what the user said is more useful than your paraphrase.
- **Include what you ruled out.** "Tried approach X, didn't work because Y" saves the next agent from repeating dead ends.
- **Be explicit about scope.** "Fix the redirect bug. Do NOT refactor the surrounding auth code, even if it looks tempting" — receiving agents will overreach without a fence.

## When to write a handoff vs. just doing the work

Write a handoff when:
- The user explicitly asks for one.
- The remaining work is well-specified but you're out of context budget, blocked on a long-running thing, or the user wants it done elsewhere (different machine, different model, async).
- The user wants a written artifact they can review before dispatching.

Don't write a handoff when:
- The task is small enough you can just do it in this conversation.
- The work needs ongoing judgment calls that can't be pinned down in a doc — a handoff to a fresh agent will produce something off-spec.
- You'd be guessing at the acceptance criteria. Ask the user instead.

## Anti-patterns

- **Vague success criteria.** "Make it work" or "clean it up" gives the receiving agent no contract. If you can't write a checklist, you can't write a handoff yet — clarify first.
- **Leaking conversation state.** Phrases like "as we discussed", "the file you looked at earlier", or "the approach we agreed on" are meaningless to a fresh agent. Make every reference self-contained.
- **Over-prescribing the plan.** The receiving agent will read the actual code and may spot a better path. Suggest, don't dictate, unless the user has explicitly chosen the approach.
- **Putting secrets in the file.** `~/tmp/` is not private. Reference secrets by env var name or path; don't paste them.
- **Forgetting to tell the user the path.** The skill's output is the file path — surface it clearly so the user can pass it to the next agent.