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)

2. Generate filename:

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

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

4. Content structure:

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

5. Commit:

   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'

2. Run verification checklist:

   Implementation Complete:

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

   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

3. Verify all checklist items:

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

4. Update metadata:

   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
   

5. Update status in document:

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

6. Move to resolved:

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

7. Commit:

   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/

2. Add RESOLVED- prefix:

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

3. Update metadata:

   status: archived
   archived_date: {today}
   

4. Commit:

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

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

2. For each handoff:

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

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