handoff

What this skill does

# Handoff

## Goal

Auto-generate a comprehensive handoff document that captures current work state, progress, and context. This supports the "Document & Clear" workflow for complex tasks - create a handoff document, `/clear` the session, then later resume by reading the handoff.

The document is saved to `/tmp` for easy copy/paste to wherever you need it (notes app, issue tracker, email, etc.).

## Input

- `$ARGUMENTS` (optional): Custom filename without extension
  - Default: `handoff-{timestamp}.md`
  - Example: `/handoff` → `/tmp/handoff-2024-01-15-1430.md`
  - Example: `/handoff auth-feature` → `/tmp/auth-feature.md`

## Process

### 1. Verify Git Repository

Check that we're in a git repository (handoff documents git state):

```bash
git rev-parse --git-dir
```

If this fails, create a minimal handoff without git context and warn the user.

### 2. Gather Git Context

Collect comprehensive git information:

```bash
# Current branch
CURRENT_BRANCH=$(git branch --show-current)

# Base branch (for comparison)
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$BASE_BRANCH" ]; then
  if git show-ref --verify --quiet refs/heads/main; then
    BASE_BRANCH="main"
  elif git show-ref --verify --quiet refs/heads/master; then
    BASE_BRANCH="master"
  else
    BASE_BRANCH="HEAD"
  fi
fi

# Commit history on current branch
git log --oneline $BASE_BRANCH..HEAD 2>/dev/null || git log --oneline -5

# Commits ahead count
COMMITS_AHEAD=$(git rev-list --count $BASE_BRANCH..HEAD 2>/dev/null || echo "unknown")

# Changed files with status
git diff --name-status $BASE_BRANCH...HEAD 2>/dev/null

# Uncommitted changes
git status --porcelain

# Recent commits with full messages
git log -5 --format="%h - %s%n%b" --no-merges

# Current git user
GIT_USER=$(git config user.name)
GIT_EMAIL=$(git config user.email)
```

### 3. Check for Existing TODO List

If TodoWrite has been used in the session, the current TODO state should be included:

- Check if there's an active TODO list
- Categorize tasks by status (completed, in_progress, pending)
- Include task descriptions in handoff

### 4. Gather File Context

For changed files, provide context:

```bash
# Count changes by status
git diff --name-status $BASE_BRANCH...HEAD | awk '{print $1}' | sort | uniq -c

# Group files by directory
git diff --name-only $BASE_BRANCH...HEAD | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn

# Diff stats for magnitude of changes
git diff --stat $BASE_BRANCH...HEAD
```

### 5. Optionally Gather User Context

Use AskUserQuestion **only if** there's significant work in progress (more than 3 commits OR uncommitted changes OR active TODOs).

Ask strategically useful questions:

```markdown
Question 1: "What's the current blocker or challenge (if any)?"
Options:
- "No blockers - work is progressing smoothly"
- "Waiting on code review or feedback"
- "Technical issue - something not working as expected"
- "Unclear requirements or design decision needed"

Question 2: "What's the most important context to remember?"
Options:
- "Implementation approach or architecture decisions"
- "Key files or functions to focus on"
- "Dependencies or integration points to be aware of"
- "No specific context - handoff document captures it"
```

Only ask if it adds value. For simple tasks (1-2 commits, clear scope), skip questions and generate automatically.

### 6. Generate Handoff Document

Create comprehensive markdown document with this structure:

```markdown
# Handoff: {Work Description from Commits or Branch Name}

**Generated**: {ISO timestamp}
**Branch**: {CURRENT_BRANCH}
**Created By**: {GIT_USER} <{GIT_EMAIL}>

---

## Quick Summary

{One-paragraph summary of what's being worked on, inferred from:
- Branch name
- Recent commit messages
- Changed files
}

## Current State

### Branch Information
- **Current Branch**: {CURRENT_BRANCH}
- **Base Branch**: {BASE_BRANCH}
- **Commits Ahead**: {COMMITS_AHEAD}
- **Uncommitted Changes**: {Yes/No} ({count} files)

### Repository Status
```
{Output from git status}
```

## Work Progress

{If TODO list exists:}

### ✅ Completed Tasks
- {List completed tasks from TODO}

### 🔄 In Progress
- {List in-progress tasks from TODO}

### ⏭️ Pending Tasks
- {List pending tasks from TODO}

{If no TODO list:}

Based on commit history, work appears to be focused on:
{Infer from commit messages what's been done}

## Changes Overview

### Commit History
```
{git log output showing commits on branch}
```

### Files Changed

**Summary**: {X} files ({A} added, {M} modified, {D} deleted)

{Group by directory:}

**{Directory}** ({count} files)
- {file1} (Status)
- {file2} (Status)

### Change Statistics
```
{git diff --stat output}
```

## Technical Context

{Analyze changes to provide context:}

### Components Modified
- {List major components/modules affected}

### Key Files to Review
{Highlight important files based on:
- Largest changes (diff stats)
- Core functionality (e.g., main.py, app.js)
- New files (might be important)
}

### Dependencies or Integration Points
{Check for changes to:
- package.json, requirements.txt, go.mod, Cargo.toml
- Config files
- API contracts
- Database migrations
}

## Known Issues or Blockers

{If user provided blocker info via AskUserQuestion, include it}
{Otherwise, check for TODO/FIXME/HACK comments in recent changes}

{If found, list them; if not:}
No known blockers documented.

## Key Decisions or Context

{If user provided context via AskUserQuestion, include it}
{Otherwise, extract from commit messages or skip}

## Resumption Guide

### To Resume This Work:

1. **Checkout the branch**:
   ```bash
   git checkout {CURRENT_BRANCH}
   ```

2. **Review current state**:
   ```bash
   git status
   git log {BASE_BRANCH}..HEAD
   ```

3. **Understand changes**:
   ```bash
   /catchup  # Use catchup command to get oriented
   ```

4. {If uncommitted changes exist:}
   **Review uncommitted work**:
   ```bash
   git diff  # See what's changed but not committed
   ```

5. **Continue implementation**:
   {If TODO list exists:}
   - Next task: {First pending task from TODO}
   {Otherwise:}
   - Review commit messages for next steps
   - Check for TODO comments in code

### Environment Setup

{Check for and include if present:}
- **Dependencies**: {Note if package.json/requirements.txt/etc changed}
- **Config Changes**: {Note if config files modified}
- **Build/Test**: {Suggest running tests if relevant}

## Related Resources

{Scan for and link to:}
- Design docs in docs/design/
- Related issues (check commit messages for #123 patterns)
- Pull requests (if branch pushed to remote)
- Related tasks files (in docs/tasks/)
}

## Next Actions

{Suggest concrete next steps based on state:}

**Immediate** (next 1-2 tasks):
1. {Infer from pending TODOs or commit history}

**Later** (follow-up work):
1. {Infer from branch scope or commit messages}

---

**How to Use This Handoff**:
- Copy this document to your notes/project management tool
- When resuming, read this document then run `/catchup` to verify current state
- Update this document if you discover new context while working
```

### 7. Save Handoff Document

Determine filename:

```bash
if [ -z "$ARGUMENTS" ]; then
  TIMESTAMP=$(date +%Y-%m-%d-%H%M)
  FILENAME="/tmp/handoff-$TIMESTAMP.md"
else
  # Sanitize filename (remove spaces, special chars)
  CLEAN_NAME=$(echo "$ARGUMENTS" | tr ' ' '-' | tr -cd 'a-zA-Z0-9-_')
  FILENAME="/tmp/$CLEAN_NAME.md"
fi
```

Write the handoff document to the file using the Write tool.

### 8. Inform User

Output:
```
✅ Handoff document created: {FILENAME}

The document includes:
- Branch state and commit history ({X} commits)
- Changed files ({Y} files)
- {If TODOs exist: Task progress (X completed, Y pending)}
- Resumption instructions

📋 Copy the file content to wherever you need it.
📁 File location: {FILENAME}

💡 To resume this work later:
   1. Read the handoff document
   2. Run /catchup to verify current state