Handoff

Skill Provenance: Handoff

Generate a structured handoff note that captures project state for the next session or a collaborator picking up the work.

When to use

Run /skill-provenance:handoff when:

• Crossing a non-persistent boundary (e.g., uploading to Claude Chat where filesystem state won't carry over).
• The session made significant decisions not yet reflected in files.
• The user explicitly asks for a handoff note.
• A collaborator or future session needs context beyond what the manifest and changelog provide.

When NOT to use: In filesystem-native environments (Claude Code, IDE) with a current manifest, changelog, and git history, a handoff note is usually unnecessary. The manifest and changelog are the handoff.

Protocol

1. Read current state. Load MANIFEST.yaml and CHANGELOG.md to understand the bundle's current version and recent history.

2. Generate the handoff note with these sections:

   • Current bundle version — name and semver from the manifest.
   • What was accomplished this session — summarize the work done, not just files changed.
   • What is stale and needs attention — files flagged as behind or not updated this session.
   • What the next session should do first — concrete first action, not vague guidance.
   • Decisions made but not yet reflected in files — architecture choices, deferred items, scope decisions that someone reading only the code wouldn't know about.
   • Per-file change summaries — for each file modified this session, a brief description of what changed (section added, field removed, logic rewritten). More granular than the changelog entry; helps the next session verify work without re-reading every file.

3. Replace, don't accumulate. A new handoff note replaces the previous one. Previous handoffs live in changelog history. Don't maintain a chain of handoff files.

4. Placement. Write the handoff note as a markdown file in the bundle directory (e.g., HANDOFF.md). Track it in the manifest with role: handoff if the user wants it to persist across sessions.

Conventions referenced

• Handoff notes are optional convenience artifacts, not required by the spec.
• The manifest and changelog are always the authoritative record. The handoff note provides context and intent that structured metadata cannot.
• In environments with persistent filesystems and git, prefer the manifest and changelog over handoff notes.

For the full spec: https://skillprovenance.dev