Managing Handoffs

Overview

Manage handoff documents through their full lifecycle: create → work → resolve → archive.

Core principle: Evidence-based verification before closing handoffs.

Announce at start: "I'm using the managing-handoffs skill to [operation]."

Handoff Metadata Template

Every handoff uses this YAML frontmatter:

yaml

---
type: handoff
status: active              # active | resolved | archived
created: YYYY-MM-DD
resolved_date: null
archived_date: null
related_sessions: []
related_plans: []
verification:
  implementation_complete: false
  documentation_exists: false
  tests_passing: false
  commits_made: false
---

Operations

Create Handoff

When: Starting new feature work or documenting incomplete work for handoff.

Process:

•
Get information:
- •Title (brief, descriptive)
- •Description (what needs to be done)
- •Related plans (implementation plan files)

•

Generate filename:

python

from datetime import date
today = date.today().strftime('%Y-%m-%d')
slug = title.lower().replace(' ', '-').replace('_', '-')
filename = f"{today}-{slug}-handoff.md"

•
Create file at: /docs/handoffs/current/{filename}

•

Content structure:

markdown

---
type: handoff
status: active
created: {today}
resolved_date: null
archived_date: null
related_sessions: []
related_plans: [{plan_paths}]
verification:
  implementation_complete: false
  documentation_exists: false
  tests_passing: false
  commits_made: false
---

# {Title}

**Created:** {today}
**Status:** 🔴 Active

## Context

{description}

## Tasks

- [ ] {task 1}
- [ ] {task 2}
- [ ] {task 3}

## Implementation Notes

[To be filled during work]

## Completion Criteria

- [ ] All tasks complete
- [ ] Code committed to git
- [ ] Documentation updated (guides/summaries)
- [ ] Tests passing (if applicable)
- [ ] Session documented

•

Commit:

bash

git add docs/handoffs/current/{filename}
git commit -m "docs: create handoff for {title}"

Close Handoff

When: Work is complete and ready to mark resolved.

Process:

•
Load handoff file
- •Read YAML frontmatter
- •Verify status is 'active'
•
Run verification checklist:

Implementation Complete:
bash
```
git log --oneline --since="$(yq -r .created handoff.md)" --grep="feat\\|fix\\|refactor"
```
- •Must have commits related to this work
- •Prompt: "Show me the commits for this work"
Documentation Exists:
- •Check if guide/summary was created or updated
- •Scan git log for docs/ changes
- •Prompt: "What documentation was created/updated?"
Tests Passing (if applicable):
bash
```
pytest tests/ -v
```
- •Run relevant tests
- •Must show 0 failures
- •Uses @superpowers:verification-before-completion
Commits Made:
- •Verify git log shows activity
- •Confirm commits reference the work
•
Verify all checklist items:
- •If ANY item fails → STOP, cannot close
- •Report what's missing
- •Ask user to complete before closing

•

Update metadata:

yaml

status: resolved
resolved_date: {today}
related_sessions: [{session_files}]
verification:
  implementation_complete: true
  documentation_exists: true
  tests_passing: true  # or N/A
  commits_made: true

•
Update status in document:
- •Change Status: 🔴 Active → 🟢 Resolved
- •Add completion date

•

Move to resolved:

bash

mv docs/handoffs/current/{filename} docs/handoffs/resolved/

•

Commit:

bash

git add docs/handoffs/
git commit -m "docs: resolve handoff - {title}

Verification complete:
- Implementation: {commits}
- Documentation: {docs}
- Tests: {status}
"

Archive Handoff

When: Handoff has been resolved and is ready for archival.

Process:

•
Verify handoff is resolved:
- •Check metadata: status must be 'resolved'
- •Must be in /docs/handoffs/resolved/

•

Add RESOLVED- prefix:

bash

mv docs/handoffs/resolved/{filename} \
   docs/handoffs/archive/RESOLVED-{filename}

•

Update metadata:

yaml

status: archived
archived_date: {today}

•

Commit:

bash

git add docs/handoffs/archive/
git commit -m "docs: archive resolved handoff - {title}"

List Handoffs

When: Checking project status, finding active work.

Process:

•

Scan handoffs/current/:

bash

find docs/handoffs/current -name "*.md" -type f

•
For each handoff:
- •Extract metadata (created date, title)
- •Calculate age (days since creation)
- •Get status

•

Output format:

code

Active Handoffs (3):

1. import-coverage-completion
   Created: 2025-11-13 (2 days ago)
   File: docs/handoffs/current/2025-11-13-import-coverage-completion-handoff.md

2. formula-correction-audit
   Created: 2025-11-13 (2 days ago)
   File: docs/handoffs/current/2025-11-13-formula-correction-audit-handoff.md

3. web-ui-phase-2
   Created: 2025-11-10 (5 days ago)
   File: docs/handoffs/current/2025-11-10-web-ui-phase-2-handoff.md

Integration

Uses:

•superpowers:verification-before-completion - Evidence-based verification

Used by:

•project-status skill - Shows active handoffs
•Development workflows - Handoff creation and closure

Common Mistakes

Closing without verification:

•Problem: Mark resolved without checking verification items
•Fix: Always run full verification checklist

Missing documentation:

•Problem: Close handoff without updating guides
•Fix: Require documentation_exists = true

Archiving active handoffs:

•Problem: Try to archive without resolving first
•Fix: Enforce status transitions (active → resolved → archived)

Red Flags

Never:

•Close handoff without verification
•Skip test verification if tests exist
•Archive directly from active status
•Modify archived handoffs

Always:

•Run verification checklist
•Link related sessions and plans
•Update status atomically
•Commit each state transition