hjemmesidekongen/ai/session-handoff

Session Handoff

Structured handoff documents for cross-session continuity. Complements automatic snapshot.yml with human-readable, chained context and staleness awareness.

Mode Selection

Creating? Save state, pause, or context getting full → CREATE below Resuming? Continue previous work → RESUME below Proactive? After 5+ file edits or major decisions, suggest creating a handoff

CREATE

1. Gather: Read snapshot.yml, active plan state.yml, git log -10, git status
2. Write handoff to .ai/handoffs/YYYY-MM-DD-HHMMSS-<slug>.md

• Sections: Current State, Important Context, Key Files, Immediate Next Steps, Pending Work, Blockers
• Include Continues-from: header linking to previous handoff or "none"
• Full template: references/process.md

1. Validate: No TODO placeholders, no secrets, referenced files exist, next steps are actionable
2. Report: File location, what was captured, first next step

RESUME

1. Find: ls .ai/handoffs/
2. Check staleness: git log --oneline --after="<date>" | wc -l

• FRESH (<5 commits): resume directly
• SLIGHTLY_STALE (5-15): review git log first
• STALE (15-30): verify assumptions, check for conflicts
• VERY_STALE (>30 or >7 days): create fresh handoff instead

1. Load: Read handoff. If chained, read predecessor too
2. Verify: Branch matches, blockers resolved, assumptions hold
3. Begin: Start with "Immediate Next Steps" item #1

Handoff Chaining

Chain handoffs via Continues-from for context lineage across sessions. Keep chains to 3-5 max; consolidate longer chains. Full detail: references/process.md.