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:

bash

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.

yaml

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

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

bash

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

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

continuity-ledger

NPX Install

Tags

SKILL.md Content