Continuity Ledger

Note: This skill is now an alias for /create_handoff. Both output the same YAML format.

Create a YAML handoff document for state preservation across /clear. This is the same as /create_handoff.

Process 1. Filepath & Metadata

First, determine the session name from existing handoffs:

ls -td thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename

This returns the most recently modified handoff folder name (e.g., open-source-release). Use this as the handoff folder name.

If no handoffs exist, use general as the folder name.

Create your file under: thoughts/shared/handoffs/{session-name}/YYYY-MM-DD_HH-MM_description.yaml, where:

{session-name} is from existing handoffs (e.g., open-source-release) or general if none exist YYYY-MM-DD is today's date HH-MM is the current time in 24-hour format (no seconds needed) description is a brief kebab-case description

Examples:

thoughts/shared/handoffs/open-source-release/2026-01-08_16-30_memory-system-fix.yaml thoughts/shared/handoffs/general/2026-01-08_16-30_bug-investigation.yaml 2. Write YAML handoff (~400 tokens)

CRITICAL: Use EXACTLY this YAML format. Do NOT deviate or use alternative field names.

The goal: and now: fields are shown in the statusline - they MUST be named exactly this.

session: {session-name from ledger} date: YYYY-MM-DD status: complete|partial|blocked outcome: SUCCEEDED|PARTIAL_PLUS|PARTIAL_MINUS|FAILED

goal: {What this session accomplished - shown in statusline} now: {What next session should do first - shown in statusline} test: {Command to verify this work, e.g., pytest tests/test_foo.py}

done_this_session: - task: {First completed task} files: [{file1.py}, {file2.py}] - task: {Second completed task} files: [{file3.py}]

blockers: [{any blocking issues}]

questions: [{unresolved questions for next session}]

decisions: - {decision_name}: {rationale}

findings: - {key_finding}: {details}

worked: [{approaches that worked}] failed: [{approaches that failed and why}]

next: - {First next step} - {Second next step}

files: created: [{new files}] modified: [{changed files}]

Field guide:

goal: + now: - REQUIRED, shown in statusline done_this_session: - What was accomplished with file references decisions: - Important choices and rationale findings: - Key learnings worked: / failed: - What to repeat vs avoid next: - Action items for next session

DO NOT use alternative field names like session_goal, objective, focus, current, etc. The statusline parser looks for EXACTLY goal: and now: - nothing else works.

1. Mark Session Outcome (REQUIRED)

IMPORTANT: Before responding to the user, you MUST ask about the session outcome.

Use the AskUserQuestion tool with these exact options:

Question: "How did this session go?" Options: - SUCCEEDED: Task completed successfully - PARTIAL_PLUS: Mostly done, minor issues remain - PARTIAL_MINUS: Some progress, major issues remain - FAILED: Task abandoned or blocked

After the user responds, mark the outcome:

Mark the most recent handoff (works with PostgreSQL or SQLite)

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-.}") cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_mark.py --latest --outcome

1. Confirm completion

After marking the outcome, respond to the user:

Handoff created! Outcome marked as [OUTCOME].

Resume in a new session with: /resume_handoff path/to/handoff.yaml

When to Use Before running /clear Context usage approaching 70%+ Multi-day implementations Complex refactors you pick up/put down Any session expected to hit 85%+ context When NOT to Use Quick tasks (< 30 min) Simple bug fixes Single-file changes Why Clear Instead of Compact?

Each compaction is lossy compression—after several compactions, you're working with degraded context. Clearing + loading the handoff gives you fresh context with full signal.