---
name: handoff-review
description: Review a handoff document for completeness, accuracy, and actionability before transitioning work. Catches missing context, unclear decisions, and vague next steps.
---

# Handoff Review

Review a handoff document before finalizing the transition. Ensures the receiving agent has everything needed to continue without asking basic questions.

## When to Use

- Before submitting a handoff (self-review)
- Before accepting a handoff from someone else (peer-review)
- When handoffs are causing repeated friction (process issue)

## Scoring

Score each dimension on 1-5:

| Score | Meaning |
|-------|---------|
| 5 | Excellent, no follow-up needed |
| 3-4 | Adequate, some clarification needed |
| 1-2 | Poor, must fix before handoff |

## Review Checklist

### 1. Completeness (Score: /5)

- [ ] Goal statement: what problem is being solved?
- [ ] State clarity: done vs in-progress vs blocked are clearly separated
- [ ] Key files listed with their purpose
- [ ] All modified files mentioned (not partial)
- [ ] Branch and commit info present

**Fail if:** reviewer can't tell what the goal was.

### 2. Decision Quality (Score: /5)

- [ ] Each decision includes WHY (rationale), not just WHAT
- [ ] Alternatives mentioned (shows it was considered)
- [ ] Known tradeoffs surfaced
- [ ] Architectural constraints documented

**Fail if:** reviewer would make a different decision because rationale is missing.

### 3. Actionability (Score: /5)

- [ ] Next steps are concrete and ordered by priority
- [ ] Each step is a clear action (not vague like "continue work")
- [ ] Blocker dependencies identified with what's needed to unblock
- [ ] Expected effort/time estimate if available

**Fail if:** reviewer can't immediately start working.

### 4. Accuracy (Score: /5)

- [ ] Branch name verified (not stale)
- [ ] Commit hashes match actual git history
- [ ] File paths exist and are correct
- [ ] Claims about what's done are verified

**Fail if:** reviewer finds factual errors in the handoff.

### 5. Safety (Score: /5)

- [ ] No secrets, credentials, tokens, or API keys
- [ ] No internal/confidential info exposed inappropriately
- [ ] No misleading statements that could cause mistakes

**Fail if:** any credential is visible. This is a blocker.

## Review Output

Write the review as a comment at the top of the handoff document:

```markdown
## Handoff Review ({YYYY-MM-DD})

| Dimension | Score | Notes |
|-----------|-------|-------|
| Completeness | X/5 | {what's missing} |
| Decision Quality | X/5 | {what's unclear} |
| Actionability | X/5 | {what's vague} |
| Accuracy | X/5 | {errors found} |
| Safety | X/5 | {issues flagged} |

**Blockers:** {items that must be fixed}
**Recommendations:** {suggestions for improvement}
**Overall:** {PASS / PASS_WITH_CAVEATS / FAIL}
```

## Results

- **PASS** (all ≥3, no fails): Handoff is ready
- **PASS_WITH_CAVEATS** (all ≥3, but 1-2 flagged): Accept with follow-ups
- **FAIL** (any score <3 or safety fail): Return for revision

## Continuous Improvement

Track common review findings to improve future handoffs:

```yaml
recurring_issues:
  - description: "Missing decision rationale"
    fix: "Document WHY for all decisions"
  - description: "Stale branch info"
    fix: "Run git commands to verify before writing"
```

## Quick Review (when time is limited)

Check just these three things:

1. **Can you state the goal after reading?** If no → FAIL
2. **Can you start working immediately?** If no → FAIL
3. **Are there any secrets visible?** If yes → BLOCKER
