Session Handoff

Session Handoff

Use this skill when the user says "handoff", "summarize this session", "create a handoff", "hand this off", or invokes /handoff.

Produce a precise handoff document and write it to a file. Do not ask the user questions — derive everything from conversation history and git state.

If the user provides arguments, treat them as the intended focus of the next session and prioritize that focus in Goal, Current State, and Next Steps. If the user says "update handoff" or similar, update the most recent handoff file in place instead of creating a new one.

This skill writes the artifact. Use handoff-receiver when the task is to continue execution from an existing handoff.

Step 1: Determine output path and index files

1. If .trellis/ exists in the working directory → write to .trellis/handoffs/YYYY-MM-DD-HH-MM.md
2. Else if docs/ exists in the working directory → write to docs/handoffs/YYYY-MM-DD-HH-MM.md
3. Otherwise → write to handoff.md in the project root
4. If the handoff directory is not the project root, maintain <handoff-dir>/CURRENT as the active pointer
5. Maintain <handoff-dir>/INDEX.md as the compact handoff index

if [ -d ".trellis" ]; then
  mkdir -p .trellis/handoffs
  HANDOFF_DIR=".trellis/handoffs"
elif [ -d "docs" ]; then
  mkdir -p docs/handoffs
  HANDOFF_DIR="docs/handoffs"
else
  HANDOFF_DIR="."
fi
if [ "$HANDOFF_DIR" = "." ]; then
  HANDOFF_PATH="handoff.md"
  CURRENT_PATH="CURRENT"
  INDEX_PATH="INDEX.md"
else
  HANDOFF_PATH="$HANDOFF_DIR/$(date +%Y-%m-%d-%H-%M).md"
  CURRENT_PATH="$HANDOFF_DIR/CURRENT"
  INDEX_PATH="$HANDOFF_DIR/INDEX.md"
fi
printf '%s\n%s\n%s\n' "$HANDOFF_PATH" "$CURRENT_PATH" "$INDEX_PATH"

Before creating a new handoff, if CURRENT points to an existing active handoff, update that file:

• status: paused
• updated_at: <now>

Do not rewrite handoffs already marked done or superseded. Use superseded only when you are explicitly replacing the same work stream.

Step 2: Gather facts from git

Run these commands to get objective facts. Do not skip any.

# What changed
git status --short
git diff --stat HEAD
git log --oneline -10

# What branch
git rev-parse --abbrev-ref HEAD

# Any stash
git stash list

Use results to populate the Files Changed and Commands Run sections.

Step 3: Extract from conversation

Review the full conversation to extract:

Be precise. Prefer concrete facts over summaries. Include file paths and line numbers where known.

Avoid duplicating content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference those artifacts by path or URL in the relevant sections instead of repeating long content.

Step 4: Write the handoff file

Use this exact template. Fill every section — write "none" if a section is genuinely empty.

---
status: open
created_at: YYYY-MM-DD HH:MM
updated_at: YYYY-MM-DD HH:MM
taken_over_at:
taken_over_by:
superseded_by:
source_handoff:
stream_note:
---

# Session Handoff

**Date**: YYYY-MM-DD HH:MM  
**Branch**: <branch name>  
**Working directory**: <absolute path>

---

## Goal

<One paragraph. What was the user trying to accomplish and why? Be specific — not "improve the app" but "add X to Y so that Z".>

---

## Files Changed

| File | Change |
|------|--------|
| `path/to/file.ts` | Added `functionName()`, removed deprecated `oldFn()` |
| `path/to/config.yml` | Updated `timeout` from 30 to 60 |

*(list only files with actual changes; omit read-only)*

---

## Commands Run

| Command | Outcome |
|---------|---------|
| `npm run build` | ✓ passed |
| `git push origin main` | ✗ rejected — no upstream set |

---

## History

Summarize the commit and branch history that matters for the next session.

Include:
- recent commit hashes
- branch rewrites or force-pushes
- merges, rebases, or resets that changed the working line of development

---

## Errors Encountered

- **Error**: `Cannot find module './utils'` in `src/index.ts:12`  
  **Resolution**: Added missing import; resolved.

- **Error**: `git push` rejected  
  **Resolution**: Unresolved — see Next Steps.

*(list errors that occurred, whether resolved or not)*

---

## Decisions Made

- **Chose X over Y** because: <reason>
- **Deferred Z** because: <reason>
- **Accepted trade-off**: <what was given up and why>

---

## Current State

<One paragraph. Where does the work stand right now? Is it working? Partially done? Blocked? What is the state of the codebase at this moment?>

---

## Next Steps

1. [ ] <Concrete action — specific file, command, or decision needed>
2. [ ] <Next action>
3. [ ] <Stretch / nice-to-have if time allows>

---

## Context for the Next Session

<Any non-obvious context a new AI or developer would need to pick this up: gotchas, environment quirks, why something was done a certain way, what was explicitly ruled out.>

Step 5: Update pointer and index

Write the final handoff path into CURRENT. Then update INDEX.md with one row per tracked handoff:

Rules:

• keep rows stable and append-only when possible
• update only minimal metadata: path, status, updated_at, short goal summary
• never duplicate full handoff bodies inside the index
• preserve paused, done, and superseded rows for historical routing

handoff-receiver should read CURRENT and INDEX.md first. It should not scan the directory in the common case.

Step 6: Confirm to user

After writing the file, output exactly:

Handoff written to: <relative path to file>

## Goal
<one sentence summary>

## Next Steps
<numbered list from the file>

Do not output the full file contents in chat — the file is the artifact. The inline summary is just a quick confirmation.

Anti-patterns

• Do not ask the user "what did we work on?" — derive from conversation.
• Do not write vague entries like "various files updated" — be specific.
• Do not skip the git commands — they provide objective ground truth.
• Do not create a new handoff if the user says "update handoff" — overwrite the most recent one.
• Do not leave multiple active handoffs without updating CURRENT.

Example

If the handoff directory contains:

• CURRENT → .trellis/handoffs/2026-05-22-12-40-open-core.md
• .trellis/handoffs/2026-05-22-12-21-onboarding.md with no status

and you create .trellis/handoffs/2026-05-22-13-10-search.md, then:

• 2026-05-22-12-40-open-core.md becomes status: paused
• 2026-05-22-12-21-onboarding.md remains untouched until indexed
• CURRENT moves to 2026-05-22-13-10-search.md
• INDEX.md contains one row for each known stream