handoff

name	handoff
description	Compact the current conversation into a handoff document so another agent can continue the work. Use when ending a coding session, switching tasks, when the context window is getting full, or before handing off to a teammate or another AI agent. Saves to OS temp directory, not the workspace.
argument-hint	[what the next session will focus on]

Session Handoff

"Every session ends. Make the next one count."

Philosophy

Sessions end. Context is lost. Hours of progress disappear. This skill prevents that by compressing the session into a document a fresh agent can use to continue immediately.

Workflow

Step 1: Capture Current State

• What was accomplished? One-line per completed task.
• What's in progress? What's done, what's remaining, any blockers.
• What was decided? Key decisions with rationale. This prevents re-litigating in the next session.

Step 2: Capture Technical Context

• Files changed — Each modified file with brief description
• Codebase state — Do tests pass? Deployable? Any temporary hacks?
• Domain knowledge gained — Insights about codebase, business logic, architecture

Step 3: Capture Next Steps

• Immediate — Must do next
• Soon — Should do soon
• Later — Nice to have

Step 4: Write the Document

# Handoff: [Session Focus]

## Completed
- [Task 1]: [summary]
- [Task 2]: [summary]

## In Progress
- [Task 3]: Done — [what's done]. Remaining — [what's left]. Blocker — [if any].

## Decisions
- [Decision 1]: [what] — Rationale: [why]
- [Decision 2]: [what] — Rationale: [why]

## Files Changed
- `path/to/file1.ts`: [description]
- `path/to/file2.ts`: [description]

## Codebase State
- Tests: [all pass / X failing — reason]
- Deployable: [yes / no — reason]
- TODOs: [temporary hacks]

## Domain Knowledge
- [Insight 1]
- [Insight 2]

## Next Steps
1. **Immediate:** [must do]
2. **Soon:** [should do]
3. **Later:** [nice to have]

## Open Questions
- [Question 1]

## Suggested Skills
- `/grill` — [why]
- `/tdd` — [why]

Step 5: Save

Save to OS temp directory (not workspace). Redact sensitive info (API keys, passwords, PII). Do not duplicate content already in PRDs, ADRs, issues, commits — reference them by path or URL.

Anti-Patterns

• Writing a novel — Use /caveman style if needed
• Omitting decisions — Future sessions WILL re-litigate without rationale
• Vague next steps — "Continue working on the feature" is not actionable
• Forgetting test state — Next session needs to know immediately

Integration

• Use /caveman to keep the handoff compact
• Use /to-issues to convert next steps into grabbable issues
• Next session should start with /grill to re-align