---
name: handoff-receive
description: Process an incoming handoff document to quickly onboard into existing work. Reads HANDOFF.md, validates context, sets up environment, and prepares to continue where the previous agent left off.
---

# Handoff Receiver

Process an incoming handoff to quickly get up to speed on existing work. Run this when picking up work from another agent or resuming your own saved context.

## When to Use

- Resuming work after a pause
- Taking over from another agent
- Starting work on a feature someone else began
- Context switching into a complex task

## Process

```
1. LOCATE: Find the handoff document(s)
2. READ: Parse the handoff completely before acting
3. VALIDATE: Verify branch, files, and environment
4. UNDERSTAND: Confirm key decisions and next steps
5. PREPARE: Set up the workspace
6. CONTINUE: Start executing next steps
```

## Steps

### 1. Locate Handoff

Search for handoff documents in priority order:
```yaml
paths:
  - HANDOFF.md (workspace root)
  - handoffs/HANDOFF-*.md (dated handoffs, pick latest)
```

Use glob to find them:
- `glob("HANDOFF.md")`
- `glob("handoffs/HANDOFF-*.md")`

### 2. Read and Parse

Read the full handoff document. Create a mental model of:
- What was the original goal?
- What's done vs what's left?
- What decisions constrain the approach?
- What blockers need unblocking?

### 3. Validate Context

Before trusting the handoff, verify key claims:

```
CHECKLIST:
- [ ] git branch exists: `git branch --list {branch}`
- [ ] git branch is current: `git rev-parse --abbrev-ref HEAD`
- [ ] Latest commit matches: `git log -1 --oneline`
- [ ] Key files exist: `Test-Path {file}` for each critical file
- [ ] Dependencies installed: check package.json, requirements.txt, etc.
- [ ] Tests still pass: run the test suite quickly
- [ ] Any uncommitted changes: `git status`
```

If any verification fails:
- Branch wrong → `git checkout {branch}` or `git stash && git checkout`
- Files missing → check if they were deleted or renamed
- Commit outdated → `git pull` or `git fetch && git log`
- Tests failing → note as new finding, don't assume handoff is wrong

### 4. Understand Key Decisions

For each key decision in the handoff:
- Read the rationale
- Check the actual code if needed
- If rationale is unclear or seems wrong, flag it

Ask: "Does this decision still make sense given what I see now?"

### 5. Prepare Workspace

```
1. git checkout {branch}
2. git pull (if shared repo)
3. Install/update deps
4. Build/compile if needed
5. Run tests to establish baseline
6. Open key files from the handoff
```

### 6. Continue Execution

Start with the **first** item in Next Steps.

If next steps are vague or missing:
- Check open questions and try to answer them
- Look at what's "In Progress" and try to complete it
- Review the code for TODO/FIXME/HACK comments
- Run tests to find failures that suggest what needs fixing

## Output

After processing the handoff, write a brief summary of what you found:

```
## Onboarding Complete

Goal: {restate goal from handoff}
Status Verified: {all checks passed / issues found}
Key Decisions Understood: {list}
Starting With: {first action}
```

This helps the next handoff if you need to pause again.

## Common Issues

| Issue | Resolution |
|-------|------------|
| Handoff is outdated | Check git log for changes since handoff was written |
| Branch doesn't exist | Check `git branch -a` for remote branches |
| Decisions not explained | Look at git blame / commit messages for rationale |
| Next steps too vague | Check open issues, TODO comments, failing tests |
| Build broken | Check CI status, dependency changes |
| Secret/credential in handoff | Flag immediately, do not commit |

## Bad Handoff Detection

If the handoff is poor (missing info, unclear), do NOT just guess. Instead:
1. Process what IS available
2. Supplement by examining the codebase directly (git log, diffs, TODOs)
3. Document what's missing so it can be improved for next time
