Handoff Skill
Quick Ref:
Create structured handoff for session continuation. Output:
.agents/handoff/YYYY-MM-DD-
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: What was the last thing done? What was about to happen next? Were we mid-task or between tasks? 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-
.md (use date +%Y-%m-%d )
Handoff:
** Status: ** < Paused mid-task | Between tasks | Blocked on X
What We Accomplished This Session
< Brief description with file: line citations ** Files changed: ** -
path/to/file.py- Description
...
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 (use date +%Y-%m-%d)
```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
- The handoff doc:
.agents/handoff/YYYY-MM-DD-<topic-slug>.md
What I Need Help With
Key Files
Open Questions
Step 8: Extract Learnings (Optional)
If significant learnings occurred this session, also run post-mortem: ```bash
Check if post-mortem 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
/post-mortem --quick
to extract learnings.
If <3 commits:
Handoff alone is sufficient; learnings are likely minimal.
Step 9: Report to User
Tell the user:
Handoff document location
Continuation prompt location
Summary of what was captured
Suggestion: Copy the continuation prompt for next session
If learnings detected, suggest
/post-mortem --quick
Output completion marker:
Capture state for continuation
/post-mortem --quick
Extract learnings for future
Both should be run when ending a productive session. Without ao CLI If ao CLI not available: Skip the ao ratchet status check in Step 2 Step 8 retro suggestion still works (uses git commit count) All handoff documents are still written to .agents/handoff/ Knowledge is captured for future sessions via handoff, just not indexed Examples Paused Mid-Implementation User says: /handoff (after working on OAuth flow for 2 hours, need to stop) What happens: Agent detects recent commits (5 commits in last 2 hours, auth-related) Agent checks in-progress work with bd list (issue #42 still open) Agent identifies pause point: "Completed token generation, about to start refresh logic" Agent lists key files: auth.go, token.go, research doc, plan doc Agent writes handoff document with accomplishments and pause state Agent writes continuation prompt with clear next action Agent checks commits (5) and suggests running /post-mortem --quick to extract learnings Result: Handoff captures state, continuation prompt ready, post-mortem suggested. Between Tasks, Clean State User says: /handoff (just closed issue #40, about to start #41 next session) What happens: Agent detects 1 commit (closed issue #40), no pending changes Agent identifies pause point: "Between tasks. Last: closed #40 (fixed rate limiting). Next: start #41 (add JWT refresh)" Agent lists files from #40 (middleware.go, config.go) Agent writes handoff with accomplishment summary and next-task preview Agent writes continuation prompt with /implement #41 suggestion Agent skips post-mortem suggestion (<3 commits) Result: Handoff captures clean boundary, continuation is simple. Auto-Derived Topic User says: /handoff (no topic provided, agent derives from commits) What happens: Agent reads recent commits: "feat: add rate limiting", "fix: token expiry" Agent derives topic slug: "rate-limiting" (from most recent commit) Agent creates handoff files with derived topic in filename Agent reports: "Handoff created: .agents/handoff/20260213T143000Z-rate-limiting.md" Result: Topic auto-derived from git history, no user input needed. Troubleshooting Problem Cause Solution "No session activity found to hand off" No commits, no file changes detected Expected for idle sessions. Nothing to hand off. Start new work or skip handoff. Handoff files not written .agents/handoff/ directory does not exist or not writable Run mkdir -p .agents/handoff or check directory permissions Topic slug is generic "session-1430" No descriptive commits or issues to derive topic from Provide explicit topic: /handoff auth-refactor for better naming Continuation prompt missing key context Recent files or artifacts not listed in handoff Manually add missing files to handoff document or re-run with explicit topic Post-mortem suggested but no learnings Agent sees ≥3 commits and auto-suggests /post-mortem --quick Run /post-mortem --quick or skip if commits are trivial (agent can't judge learning quality, only commit count) See Also skills/post-mortem/SKILL.md — Full validation + knowledge lifecycle (council + extraction + activation + retirement) skills/retro/SKILL.md — Quick-capture a learning