# Create Handoff

> Create handoff document for transferring work to another session

- Skill: `parcadei/create-handoff-2` (Agent Skill)
- Install (CLI): `npx get-skill add parcadei/create-handoff-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/parcadei/create-handoff-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: parcadei (https://skillmd.com/u/parcadei)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/parcadei/create-handoff-2

---


Handoffs transfer mental model to fresh sessions. Cardinal sin: forcing next instance to re-discover what you know.

First determine session folder from existing handoffs: `ls -td thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename`. Returns most recent folder name (e.g., `open-source-release`). Use this name, or `general` if none exist.

Create file at `thoughts/shared/handoffs/{session-name}/YYYY-MM-DD_HH-MM_description.yaml` using today's date/time and brief kebab-case description.

Use EXACTLY this YAML format — `goal:` and `now:` fields appear in statusline and must be named precisely:

```yaml
---
session: {session-name from ledger}
date: YYYY-MM-DD
status: complete|partial|blocked
outcome: SUCCEEDED|PARTIAL_PLUS|PARTIAL_MINUS|FAILED
---

# ── STATUSLINE (REQUIRED — parsed by hooks) ──────────────────────
goal: {What this session accomplished - shown in statusline}
now: {What next session should do first - shown in statusline}
test: {Command to verify this work, e.g., pytest tests/test_foo.py}

# ── MENTAL MODEL (REQUIRED) ──────────────────────────────────────
mental_model: |
  {3-10 lines explaining how the system ACTUALLY works as you discovered
  during this session. Include non-obvious behaviors, execution order, real
  data flow, surprises. Example: "Hook system runs PreToolUse before
  permission checks. Order: PreToolUse hooks → permission check → tool
  execution → PostToolUse hooks. Hooks dir .claude/hooks/dist/ contains
  compiled JS — TS source in .claude/hooks/src/ needs npm run build."}

# ── CODEBASE STATE (REQUIRED) ────────────────────────────────────
codebase_state:
  builds: true|false
  tests_passing: {N}/{total}
  test_command: {e.g., cargo test -p tldr-cli}
  pre_existing_failures: [{any failures NOT from this session}]
  uncommitted_changes: true|false
  branch: {current branch}
  dirty_files: [{modified/staged files relevant to this work}]
  warnings: {known warnings to ignore, or "clean"}

# ── WHAT WAS DONE ────────────────────────────────────────────────
done_this_session:
  - task: {completed task}
    files: [{file1.py}, {file2.py}]
  - task: {second completed task}
    files: [{file3.py}]

# ── DECISIONS (capture WHY) ──────────────────────────────────────
decisions:
  - name: {decision_name}
    chose: {what was chosen}
    over: [{rejected alternatives}]
    because: {actual reason — constraints, user preference, technical}
    constraint: {non-negotiable constraint if any}

# ── FINDINGS (tiered by importance) ──────────────────────────────
findings:
  critical:
    - {thing next instance MUST know or they'll waste time}
  useful:
    - {helpful context that saves time}
  fyi:
    - {nice-to-know background}

# ── APPROACHES ───────────────────────────────────────────────────
worked: [{approaches that worked}]

failed:
  - attempted: {what you tried}
    root_cause: {real reason it didn't work}
    avoid: {what class of approaches to skip}
    use_instead: {what to do instead if known}

# ── TRAJECTORY (include if task evolved) ─────────────────────────
trajectory:
  started_as: {original request/framing}
  evolved_to: {what it became after discussion/discovery}
  scoped_to: {final agreed scope}
  user_approved_scope: true|false

# ── USER INTENT (include when non-obvious) ───────────────────────
user_intent: |
  {Real context behind request. E.g., "Preparing for demo — visual polish
  matters more than architecture" or "Exploring viability — be ready to
  pivot entirely" or "User prefers minimal changes over full refactor."}

# ── HYPOTHESES (REQUIRED when status: partial|blocked) ───────────
hypotheses:
  - status: active|confirmed|ruled_out
    claim: {what you think is happening}
    evidence: [{supporting observations}]
    next_test: {what to try next to confirm/deny}

# ── BLOCKERS & QUESTIONS ─────────────────────────────────────────
blockers: [{blocking issues}]
questions: [{unresolved questions for next session}]

# ── NEXT STEPS ───────────────────────────────────────────────────
next:
  - {specific step with file paths, function names, line numbers}
  - {second step}

# ── NEXT SESSION PROMPT (REQUIRED) ───────────────────────────────
next_session_prompt: |
  {Write as if you're the user talking to fresh Claude instance.
  3-15 lines, direct and specific. Example:

  "Continue implementing CSV export in src/export/csv.rs. Struct
  CsvWriter defined at line 42 but write_row() is stub. Use same
  pattern as JsonWriter in src/export/json.rs:58-90. Tests in
  tests/export_csv.rs — 3 of 7 passing. Remaining 4 need write_row()
  to work. Run `cargo test -p export` to verify. Don't change public
  API — agreed with user in previous session."}

# ── FILE MANIFEST ────────────────────────────────────────────────
files:
  created: [{new files}]
  modified: [{changed files}]
```

**Section Requirements by Status:** `goal:`/`now:`/`mental_model:`/`codebase_state:` always required. `done_this_session:` required unless blocked with no progress. `findings:` required for complete, optional for partial/blocked. `hypotheses:` required for partial/blocked, skip for complete. `trajectory:`/`user_intent:` when non-obvious. `next_session_prompt:` always required.

**Quality Gates:** Mental model test — would fresh instance avoid your first 20 minutes of mistakes? Decision test — could they judge validity if circumstances changed? Dead end test — would they avoid the failure class, not just exact attempt? Intent test — could they continue without clarifying questions? State test — could they start coding in 30 seconds? Prompt test — is next_session_prompt immediately actionable?

**Guidelines:** More information beats less. Be thorough and precise with both high-level objectives and low-level details. Avoid large code blocks — use file:line references like `src/auth.ts:42-68 (validateToken)`. Mental model IS the handoff — everything else is metadata. Be explicit about implicit knowledge.

