Handoff Skill

Quick Ref: Create structured handoff for session continuation. Output: .agents/handoff/YYYY-MM-DD-<topic>.md + continuation prompt.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Create a handoff document that enables seamless session continuation.

Execution Steps

Given /handoff [topic]:

Step 1: Create Output Directory

mkdir -p .agents/handoff

Step 2: Identify Session Context

If topic provided: Use it as the handoff identifier.

If no topic: Derive from recent activity:

# Recent commits
git log --oneline -5 --format="%s" | head -1

# Check current issue
bd current 2>/dev/null | head -1

# Check ratchet state
ao ratchet status 2>/dev/null | head -3

Use the most descriptive source as the topic slug.

Topic slug format: 2-4 words, lowercase, hyphen-separated (e.g., auth-refactor, api-validation). Fallback: If no good topic found, use session-$(date +%H%M) (e.g., session-1430).

Step 3: Gather Session Accomplishments

Review what was done this session:

# Recent commits this session (last 2 hours)
git log --oneline --since="2 hours ago" 2>/dev/null

# Recent file changes
git diff --stat HEAD~5 2>/dev/null | head -20

# Research produced
ls -lt .agents/research/*.md 2>/dev/null | head -3

# Plans created
ls -lt .agents/plans/*.md 2>/dev/null | head -3

# Issues closed
bd list --status closed --since "2 hours ago" 2>/dev/null | head -5

Step 4: Identify Pause Point

Determine where we stopped:

1. What was the last thing done?
2. What was about to happen next?
3. Were we mid-task or between tasks?
4. Any blockers or decisions pending?

Check for in-progress work:

bd list --status in_progress 2>/dev/null | head -5

Step 5: Identify Key Files to Read

List files the next session should read first:

• Recently modified files (core changes)
• Research/plan artifacts (context)
• Any files mentioned in pending issues

# Recently modified
git diff --name-only HEAD~5 2>/dev/null | head -10

# Key artifacts
ls .agents/research/*.md .agents/plans/*.md 2>/dev/null | tail -5

Step 6: Write Handoff Document

Write to: .agents/handoff/YYYY-MM-DD-<topic-slug>.md

# Handoff: <Topic>

**Date:** YYYY-MM-DD
**Session:** <brief session description>
**Status:** <Paused mid-task | Between tasks | Blocked on X>

---

## What We Accomplished This Session

### 1. <Accomplishment 1>

<Brief description with file:line citations>

**Files changed:**
- `path/to/file.py` - Description

### 2. <Accomplishment 2>

...

---

## Where We Paused

<Clear description of pause point>

**Last action:** <what was just done>
**Next action:** <what should happen next>
**Blockers (if any):** <anything blocking progress>

---

## Context to Gather for Next Session

1. <Context item 1> - <why needed>
2. <Context item 2> - <why needed>

---

## Questions to Answer

1. <Open question needing decision>
2. <Clarification needed>

---

## Files to Read

Priority files (read first)

path/to/critical-file.py .agents/research/YYYY-MM-DD-topic.md

Secondary files (for context)

path/to/related-file.py

### Step 7: Write Continuation Prompt

**Write to:** `.agents/handoff/YYYY-MM-DD-<topic-slug>-prompt.md`

```markdown
# Continuation Prompt for New Session

Copy/paste this to start the next session:

---

## Context

<2-3 sentences describing the work and where we paused>

## Read First

1. The handoff doc: `.agents/handoff/YYYY-MM-DD-<topic-slug>.md`
2. <Other critical files>

## What I Need Help With

<Clear statement of what the next session should accomplish>

## Key Files

Open Questions

1. <Question 1>
2. <Question 2>

<Suggested skill to invoke, e.g., “Use /implement to continue”>

### Step 8: Extract Learnings (Optional)

If significant learnings occurred this session, also run retro:

```bash
# Check if retro skill should be invoked
# (if >3 commits or major decisions made)
git log --oneline --since="2 hours ago" 2>/dev/null | wc -l

If ≥3 commits: Suggest running /retro to extract learnings. If <3 commits: Handoff alone is sufficient; learnings are likely minimal.

Step 9: Report to User

Tell the user:

1. Handoff document location
2. Continuation prompt location
3. Summary of what was captured
4. Suggestion: Copy the continuation prompt for next session
5. If learnings detected, suggest /retro

Output completion marker:

<promise>DONE</promise>

If no context to capture (no commits, no changes):

<promise>EMPTY</promise>
Reason: No session activity found to hand off

Example Output

Handoff created:
  .agents/handoff/2026-01-31-auth-refactor.md
  .agents/handoff/2026-01-31-auth-refactor-prompt.md

Session captured:
- 5 commits, 12 files changed
- Paused: mid-implementation of OAuth flow
- Next: Complete token refresh logic

To continue: Copy the prompt from auth-refactor-prompt.md

<promise>DONE</promise>

Key Rules

• Capture state, not just summary – next session needs to pick up exactly where we left off
• Identify blockers clearly – don’t leave the next session guessing
• List files explicitly – paths, not descriptions
• Write the continuation prompt – make resumption effortless
• Cite everything – file:line for all references

Integration with /retro

Handoff captures state for continuation. Retro captures learnings for the flywheel.

For a clean session end:

/handoff  # Capture state for continuation
/retro    # Extract learnings for future

Both should be run when ending a productive session.

Without ao CLI

If ao CLI not available:

1. Skip the ao ratchet status check in Step 2
2. Step 8 retro suggestion still works (uses git commit count)
3. All handoff documents are still written to .agents/handoff/
4. Knowledge is captured for future sessions via handoff, just not indexed