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:

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

1. Get information:

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

1. 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" ``

1. Create file at: /docs/handoffs/current/{filename}

1. Content structure:

```markdown

type: handoff status: active created: {today} resolveddate: null archiveddate: null relatedsessions: [] relatedplans: [{planpaths}] verification: implementationcomplete: false documentationexists: false testspassing: 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 ```

1. 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:

1. Load handoff file

- Read YAML frontmatter - Verify status is 'active'

1. 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

1. Verify all checklist items:

- If ANY item fails → STOP, cannot close - Report what's missing - Ask user to complete before closing

1. Update metadata:

``yaml status: resolved resolveddate: {today} relatedsessions: [{sessionfiles}] verification: implementationcomplete: true documentationexists: true testspassing: true # or N/A commits_made: true ``

1. Update status in document:

- Change Status: 🔴 Active → 🟢 Resolved - Add completion date

1. Move to resolved:

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

1. 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:

1. Verify handoff is resolved:

- Check metadata: status must be 'resolved' - Must be in /docs/handoffs/resolved/

1. Add RESOLVED- prefix:

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

1. Update metadata:

``yaml status: archived archived_date: {today} ``

1. 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:

1. Scan handoffs/current/:

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

1. For each handoff:

- Extract metadata (created date, title) - Calculate age (days since creation) - Get status

1. Output format:

``` 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