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:

## 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:

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:

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

SKILL.md 3.5 KB History Raw