Context Restoration Skill

Context Restoration Skill

Purpose

Restore complete session state after context loss events (auto-compact, session break, interruption).

Zero Context Loss Promise: When combined with context-checkpoint skill, users can resume exactly where they left off regardless of auto-compact events or session boundaries.

---

Inputs

Required:

• checkpoint_id (string): Unique checkpoint identifier (e.g., "SHANNON-W2-20251103T143000")

Optional:

• auto_select (boolean): Automatically select most recent checkpoint if ID not provided (default: true)
• project_id (string): Filter checkpoints by specific project
• validate_integrity (boolean): Verify checkpoint integrity via SHA-256 hash (default: true)

---

When to Use This Skill

Activate context-restoration when:

1. After Auto-Compact - Claude Code compressed conversation history
2. New Session Start - User returns after hours/​days
3. Context Loss Detection - Claude doesn't remember recent work
4. Project Switching - Loading different project context
5. Error Recovery - Restoring from last known good state

---

Workflow

Step 1: Identify Checkpoint

Input Options:
  - Checkpoint ID: "precompact_checkpoint_20250930T143000Z"
  - Auto Mode: Find most recent checkpoint automatically
  - Project-Specific: Latest checkpoint for specific project
  - Phase-Specific: Checkpoint from specific phase

Auto-Detection Logic:

# Priority order for auto-selection:
1. Read "latest_checkpoint" pointer from Serena
2. If not found, list all checkpoints and sort by timestamp
3. Select most recent checkpoint
4. Validate checkpoint is not corrupted

Step 2: Retrieve Checkpoint from Serena

Serena MCP Operation:

# Method 1: Direct retrieval (if ID known)
checkpoint_data = read_memory(checkpoint_id)

# Method 2: Auto-selection
latest_key = read_memory("latest_checkpoint")
checkpoint_data = read_memory(latest_key)

# Method 3: Search and filter
all_keys = list_memories()
checkpoint_keys = [k for k in all_keys if "checkpoint" in k]
sorted_keys = sorted(checkpoint_keys, reverse=True)
checkpoint_data = read_memory(sorted_keys[0])

Step 3: Deserialize Checkpoint JSON

Checkpoint Structure:

{
  "metadata": {
    "timestamp": "2025-09-30T14:30:00Z",
    "checkpoint_type": "precompact|manual|wave|phase|time",
    "session_id": "unique_session_identifier",
    "shannon_version": "4.0.0"
  },

  "project_state": {
    "project_id": "taskapp_v1",
    "active_phase": "implementation",
    "current_wave": 3,
    "total_waves": 5
  },

  "serena_memory_keys": [
    "spec_analysis_taskapp",
    "phase_plan_taskapp",
    "wave_1_complete_taskapp",
    "wave_2_complete_taskapp",
    "wave_3_results_frontend",
    "project_decisions_taskapp",
    "todo_list_taskapp"
  ],

  "active_work": {
    "current_focus": "Implementing authentication system",
    "in_progress_files": [
      "/​path/​to/​auth.ts",
      "/​path/​to/​login.tsx"
    ],
    "pending_tasks": [
      "Complete JWT token generation",
      "Add refresh token logic",
      "Test login flow"
    ]
  },

  "wave_context": {
    "completed_waves": [
      {
        "wave_number": 1,
        "name": "Frontend Components",
        "status": "complete",
        "agents": ["frontend-architect", "implementation-worker"],
        "results_key": "wave_1_complete_taskapp"
      }
    ],
    "pending_waves": [
      {
        "wave_number": 3,
        "name": "Database Integration",
        "status": "in_progress"
      }
    ]
  },

  "agent_context": {
    "active_agents": ["implementation-worker"],
    "agent_handoff_data": {
      "from_agent": "backend-architect",
      "to_agent": "implementation-worker",
      "context": "Complete auth implementation per plan"
    }
  },

  "key_decisions": [
    {
      "decision": "Use JWT with refresh tokens",
      "rationale": "Security best practice",
      "timestamp": "2025-09-30T14:15:00Z"
    }
  ],

  "validation_status": {
    "phase_2_gates": "passed",
    "phase_3_gates": "in_progress",
    "tests_passing": true,
    "known_issues": []
  }
}

Step 4: Restore Context State

Restoration Sequence:

# 4.1: Restore All Serena Memory Keys
serena_keys = checkpoint_data["serena_memory_keys"]
restored_memories = {}

for key in serena_keys:
    try:
        content = read_memory(key)
        restored_memories[key] = content
    except Exception as e:
        log_warning(f"Could not restore memory: {key}")
        missing_memories.append(key)

# 4.2: Rebuild Project Context
project_id = checkpoint_data["project_state"]["project_id"]
active_phase = checkpoint_data["project_state"]["active_phase"]
current_wave = checkpoint_data["project_state"]["current_wave"]
total_waves = checkpoint_data["project_state"]["total_waves"]

# 4.3: Restore Work State
current_focus = checkpoint_data["active_work"]["current_focus"]
pending_tasks = checkpoint_data["active_work"]["pending_tasks"]
in_progress_files = checkpoint_data["active_work"]["in_progress_files"]

# 4.4: Restore Wave Progress
completed_waves = checkpoint_data["wave_context"]["completed_waves"]
pending_waves = checkpoint_data["wave_context"]["pending_waves"]

# 4.5: Restore Agent State
active_agents = checkpoint_data["agent_context"]["active_agents"]
handoff_data = checkpoint_data["agent_context"]["agent_handoff_data"]

# 4.6: Restore Decisions
key_decisions = checkpoint_data["key_decisions"]

Step 5: Reinitialize MCP Connections

MCP Validation:

# Check required MCPs are available
required_mcps = ["serena"]  # From skill frontmatter

for mcp_name in required_mcps:
    try:
        # Test MCP connection
        test_mcp_connection(mcp_name)
    except:
        warn_user(f"MCP {mcp_name} not available - some features may not work")

# Reconnect to project-specific MCPs
project_mcps = checkpoint_data.get("project_mcps", [])
for mcp_config in project_mcps:
    try:
        initialize_mcp(mcp_config)
    except:
        warn_user(f"Could not initialize {mcp_config['name']}")

Step 6: Validate Restoration

Validation Checks:

validation_results = {
    # Checkpoint integrity
    "checkpoint_loaded": checkpoint_data is not None,
    "checkpoint_valid": validate_checkpoint_schema(checkpoint_data),

    # Memory restoration
    "memories_restored": len(restored_memories) > 0,
    "critical_memories_present": all([
        "spec_analysis" in str(restored_memories.keys()),
        "phase_plan" in str(restored_memories.keys())
    ]),

    # State validity
    "phase_valid": active_phase in ["analysis", "planning", "implementation", "testing", "deployment"],
    "wave_valid": current_wave > 0 and current_wave <= total_waves,

    # File references
    "files_exist": all([
        os.path.exists(f) for f in in_progress_files
    ]),

    # MCP availability
    "mcps_available": all([
        check_mcp_available(mcp) for mcp in required_mcps
    ])
}

all_valid = all(validation_results.values())

Handling Validation Failures:

if not all_valid:
    failed_checks = [k for k, v in validation_results.items() if not v]

    # Categorize failures
    critical_failures = [f for f in failed_checks if f in CRITICAL_CHECKS]
    non_critical_failures = [f for f in failed_checks if f not in CRITICAL_CHECKS]

    if critical_failures:
        warn_user("Critical restoration issues detected:")
        for failure in critical_failures:
            print(f"  ❌ {failure}")
        print("\nAttempting partial restoration...")

    if non_critical_failures:
        info_user("Non-critical issues (can proceed):")
        for failure in non_critical_failures:
            print(f"  ⚠️  {failure}")

Step 7: Present Restoration Summary

Summary Report Format:

✅ Context Restored Successfully

📦 Checkpoint Details:
   ID: precompact_checkpoint_20250930T143000Z
   Type: precompact
   Saved: 2025-09-30 14:30:00 UTC
   Age: 2 hours ago

📚 Memory Restoration:
   ✓ Restored 12 of 12 Serena memories
   ✓ Spec analysis: Available
   ✓ Phase plan: Available
   ✓ Wave results: 2 waves complete

🔄 Project State:
   Project: taskapp_v1
   Phase: Implementation (3 of 5)
   Wave: 3 of 5 (Database Integration)
   Progress: 40% complete

🎯 Current Focus:
   "Implementing authentication system"

📋 Pending Tasks:
   1. Complete JWT token generation
   2. Add refresh token logic
   3. Test login flow

📁 In-Progress Files:
   - /​path/​to/​auth.ts
   - /​path/​to/​login.tsx

🏆 Completed Waves:
   Wave 1: Frontend Components ✓
   Wave 2: Backend API ✓

🚀 Next Wave:
   Wave 3: Database Integration (in progress)
   Wave 4: Testing & Validation (planned)
   Wave 5: Deployment & Docs (planned)

🔌 MCP Status:
   ✓ Serena MCP: Connected

▶️  Ready to continue where you left off.

Step 8: Resume Execution

Continuation Logic:

# User can immediately continue working
# All context is restored, no re-specification needed

# If wave was in progress:
if current_wave_status == "in_progress":
    print(f"\nResuming Wave {current_wave}: {current_wave_name}")

    # Load wave plan
    wave_plan = read_memory(f"wave_{current_wave}_plan")

    # Check what was completed
    completed_steps = wave_plan["completed_steps"]
    remaining_steps = wave_plan["remaining_steps"]

    print(f"Completed: {len(completed_steps)} steps")
    print(f"Remaining: {len(remaining_steps)} steps")
    print(f"\nNext step: {remaining_steps[0]}")

# If between waves:
elif current_wave_status == "complete":
    print(f"\nWave {current_wave} is complete.")
    print(f"Ready to start Wave {current_wave + 1}: {next_wave_name}")
    print("\nType /​shannon:wave to begin next wave")

---

Outputs

Restoration summary object:

{
  "success": true,
  "checkpoint_id": "SHANNON-W2-20251103T143000",
  "checkpoint_type": "wave-checkpoint",
  "checkpoint_age_hours": 2,
  "restoration_timestamp": "2025-11-03T16:30:00Z",
  "memories_restored": {
    "total": 12,
    "critical": 4,
    "important": 5,
    "optional": 3
  },
  "project_state": {
    "project_id": "taskapp_v1",
    "active_phase": "implementation",
    "current_wave": 3,
    "total_waves": 5,
    "progress_percent": 40
  },
  "current_focus": "Implementing authentication system",
  "pending_tasks": [
    "Complete JWT token generation",
    "Add refresh token logic",
    "Test login flow"
  ],
  "in_progress_files": [
    "/​path/​to/​auth.ts",
    "/​path/​to/​login.tsx"
  ],
  "completed_waves": [
    {"wave_number": 1, "name": "Frontend Components"},
    {"wave_number": 2, "name": "Backend API"}
  ],
  "mcp_status": {
    "serena": "connected",
    "sequential": "available",
    "puppeteer": "not_available"
  },
  "validation": {
    "checkpoint_integrity": true,
    "all_memories_restored": true,
    "files_exist": true,
    "state_valid": true
  },
  "next_steps": [
    "Resume Wave 3: Database Integration",
    "Continue authentication implementation",
    "Run functional tests after JWT complete"
  ]
}

---

Success Criteria

This skill succeeds if:

1. ✅ Checkpoint Located: Checkpoint found in Serena MCP and successfully retrieved
2. ✅ Memories Restored: All critical Serena memories loaded without errors
3. ✅ State Valid: Project state, wave context, and agent states are coherent
4. ✅ Files Available: All referenced in-progress files exist on filesystem
5. ✅ MCPs Connected: Required MCPs (Serena) are available and functional
6. ✅ User Informed: Clear restoration summary presented with next steps
7. ✅ Resumable: User can immediately continue work without re-specification

Validation:

def validate_restoration(result):
    # Check checkpoint loaded
    assert result['success'] == True
    assert result['checkpoint_id'] is not None

    # Check memories restored
    assert result['memories_restored']['total'] > 0
    assert result['memories_restored']['critical'] > 0

    # Check state validity
    assert result['project_state']['project_id'] is not None
    assert result['project_state']['current_wave'] > 0
    assert result['project_state']['progress_percent'] >= 0

    # Check validation passed
    assert result['validation']['checkpoint_integrity'] == True
    assert result['validation']['state_valid'] == True

    # Check next steps provided
    assert len(result['next_steps']) >= 2

---

Examples

Example 1: Auto-Restore Most Recent Checkpoint

Input:

{
  "auto_select": true
}

Process:

1. Read "latest_checkpoint" pointer from Serena
2. Retrieve checkpoint: "SHANNON-W2-20251103T143000"
3. Deserialize checkpoint JSON
4. Restore 12 Serena memories
5. Rebuild project state (Wave 2 complete, Wave 3 in progress)
6. Validate integrity (all checks pass)
7. Present restoration summary

Output:

{
  "success": true,
  "checkpoint_id": "SHANNON-W2-20251103T143000",
  "checkpoint_age_hours": 2,
  "memories_restored": {"total": 12, "critical": 4},
  "project_state": {
    "project_id": "taskapp_v1",
    "current_wave": 3,
    "progress_percent": 40
  },
  "current_focus": "Implementing authentication system",
  "next_steps": [
    "Resume Wave 3: Database Integration",
    "Continue authentication implementation"
  ]
}

Example 2: Restore Specific Checkpoint

Input:

{
  "checkpoint_id": "SHANNON-W1-20251103T120000",
  "validate_integrity": true
}

Process:

1. Retrieve specified checkpoint from Serena
2. Verify SHA-256 integrity hash
3. Restore Wave 1 state (earlier checkpoint)
4. Warn user about potential loss of later work
5. Present restoration summary with confirmation

Output:

{
  "success": true,
  "checkpoint_id": "SHANNON-W1-20251103T120000",
  "checkpoint_age_hours": 6,
  "warning": "This checkpoint is from 6 hours ago. Work after this point may be lost.",
  "project_state": {
    "current_wave": 1,
    "progress_percent": 15
  },
  "next_steps": ["Resume from Wave 1 completion"]
}

Example 3: Restoration with Missing Memories

Input:

{
  "checkpoint_id": "SHANNON-W3-20251103T150000"
}

Process:

1. Retrieve checkpoint from Serena
2. Attempt to restore 15 memories
3. 3 memories missing (2 optional, 1 important)
4. Partial restoration successful
5. Warn user about incomplete context

Output:

{
  "success": true,
  "checkpoint_id": "SHANNON-W3-20251103T150000",
  "memories_restored": {"total": 12, "missing": 3},
  "warnings": [
    "3 memories could not be restored",
    "Missing: wave_2_agent_states (important)",
    "Context may be incomplete for Wave 3"
  ],
  "next_steps": [
    "Review missing context before continuing",
    "Consider re-running Wave 2 synthesis if needed"
  ]
}

---

Restoration Scenarios

Scenario 1: Auto-Compact Recovery

Context: Claude Code auto-compacted, context lost

Restoration:

# User notices context loss
# User: "What were we working on?"

# Auto-detection triggers
if detect_context_loss():
    print("🔍 Context loss detected. Checking for recent checkpoint...")

    # Find most recent checkpoint
    latest = read_memory("latest_checkpoint")
    checkpoint = read_memory(latest)

    if checkpoint:
        print(f"✓ Found checkpoint: {latest}")
        print(f"  Saved: {checkpoint['metadata']['timestamp']}")
        print("\nRestoring context...")

        restore_from_checkpoint(checkpoint)

        print("✅ Context restored. Resuming from saved state.")
    else:
        print("❌ No checkpoint found. Unable to restore context.")

Scenario 2: Specific Checkpoint Recovery

Context: User wants to restore from specific checkpoint (not latest)

Restoration:

# User: /​shannon:restore precompact_checkpoint_20250930T120000Z

checkpoint_id = "precompact_checkpoint_20250930T120000Z"

# Retrieve specific checkpoint
checkpoint = read_memory(checkpoint_id)

if checkpoint:
    print(f"Found checkpoint: {checkpoint_id}")
    print(f"Saved: {checkpoint['metadata']['timestamp']}")
    print(f"Type: {checkpoint['metadata']['checkpoint_type']}")
    print(f"\nThis will restore state from that point in time.")
    print(f"Current work after this checkpoint will be lost.")

    # Confirm before restoring
    confirm = input("Continue? (yes/​no): ")

    if confirm.lower() == "yes":
        restore_from_checkpoint(checkpoint)
        print("✅ Restored from checkpoint")
    else:
        print("Cancelled")
else:
    print(f"❌ Checkpoint not found: {checkpoint_id}")

    # Show available checkpoints
    all_checkpoints = list_checkpoint_keys()
    print(f"\nAvailable checkpoints:")
    for cp in all_checkpoints[-5:]:  # Show last 5
        print(f"  - {cp}")

Scenario 3: Project Switch Recovery

Context: User switching from Project A to Project B

Restoration:

# User: "Switch to project taskapp_v2"

# Save current project state (if active)
if current_project:
    print(f"Saving {current_project} state...")
    create_checkpoint("manual")
    print(f"✓ {current_project} state saved")

# Load new project state
target_project = "taskapp_v2"

# Find most recent checkpoint for target project
project_checkpoints = find_project_checkpoints(target_project)

if project_checkpoints:
    latest = project_checkpoints[0]
    checkpoint = read_memory(latest)

    print(f"\nLoading {target_project}...")
    restore_from_checkpoint(checkpoint)
    print(f"✅ Switched to {target_project}")
else:
    print(f"\n⚠️  No checkpoint found for {target_project}")
    print("Starting fresh project context")

Error Handling

Missing Checkpoint

def handle_missing_checkpoint(checkpoint_id):
    """Handle case where checkpoint doesn't exist"""

    print(f"❌ Checkpoint not found: {checkpoint_id}")

    # Search for similar checkpoints
    all_keys = list_memories()
    similar = fuzzy_match_keys(checkpoint_id, all_keys)

    if similar:
        print("\nDid you mean one of these?")
        for key in similar[:5]:
            print(f"  - {key}")

    # Show all available checkpoints
    checkpoint_keys = [k for k in all_keys if "checkpoint" in k]

    if checkpoint_keys:
        print("\nAll available checkpoints:")
        for key in sorted(checkpoint_keys, reverse=True)[:10]:
            cp_data = read_memory(key)
            timestamp = cp_data.get("metadata", {}).get("timestamp", "unknown")
            print(f"  - {key} ({timestamp})")
    else:
        print("\n⚠️  No checkpoints available")
        print("Consider running /​shannon:checkpoint to create one")

Corrupted Checkpoint

def handle_corrupted_checkpoint(checkpoint_id, error):
    """Handle checkpoint that exists but is corrupted"""

    print(f"❌ Checkpoint corrupted: {checkpoint_id}")
    print(f"Error: {error}")

    # Try to extract partial data
    try:
        raw_data = read_memory(checkpoint_id)

        # Check what's salvageable
        if "project_state" in raw_data:
            print("\n✓ Project state recoverable")

        if "serena_memory_keys" in raw_data:
            print("✓ Memory keys list recoverable")

            # Try to restore memories directly
            keys = raw_data["serena_memory_keys"]
            print(f"\nAttempting to restore {len(keys)} memories directly...")

            restored = {}
            for key in keys:
                try:
                    restored[key] = read_memory(key)
                except:
                    pass

            print(f"✓ Restored {len(restored)} of {len(keys)} memories")

            if len(restored) > 0:
                print("\nPartial restoration successful")
                return restored

    except Exception as e:
        print(f"Cannot salvage checkpoint: {e}")

    # Suggest alternatives
    print("\nSuggested actions:")
    print("  1. Try restoring from different checkpoint")
    print("  2. Check Serena memory keys manually")
    print("  3. Re-analyze project if needed")

Missing Memory Keys

def handle_missing_memories(checkpoint_data, missing_keys):
    """Handle case where some memory keys don't exist"""

    print(f"⚠️  {len(missing_keys)} memories could not be restored:")

    # Categorize by importance
    critical = []
    important = []
    optional = []

    for key in missing_keys:
        if any(x in key for x in ["spec_analysis", "phase_plan"]):
            critical.append(key)
        elif any(x in key for x in ["wave_", "decisions"]):
            important.append(key)
        else:
            optional.append(key)

    if critical:
        print("\n❌ CRITICAL memories missing:")
        for key in critical:
            print(f"  - {key}")
        print("\nThese are required for proper restoration.")
        print("Recommend re-running specification analysis.")
        return False

    if important:
        print("\n⚠️  IMPORTANT memories missing:")
        for key in important:
            print(f"  - {key}")
        print("\nYou can continue but some context will be incomplete.")

    if optional:
        print(f"\nℹ️  {len(optional)} optional memories missing (not critical)")

    # Ask user if they want to continue
    if important:
        response = input("\nContinue with partial restoration? (yes/​no): ")
        return response.lower() == "yes"

    return True  # Can continue if only optional missing

MCP Unavailable

def handle_mcp_unavailable(mcp_name):
    """Handle case where required MCP is not available"""

    print(f"❌ Required MCP not available: {mcp_name}")

    if mcp_name == "serena":
        print("\nSerena MCP is REQUIRED for context restoration.")
        print("Without Serena, cannot retrieve checkpoint data.")
        print("\nPlease install Serena MCP and try again:")
        print("  1. Check MCP configuration")
        print("  2. Restart Claude Code")
        print("  3. Verify Serena is running")
        return False
    else:
        print(f"\n{mcp_name} MCP is recommended but not critical.")
        print("Restoration will continue with reduced functionality.")
        return True

Best Practices

1. Always Validate Before Restoring

# Don't blindly restore - validate first
checkpoint = read_memory(checkpoint_id)

# Check age
age = calculate_age(checkpoint["metadata"]["timestamp"])
if age > timedelta(days=7):
    warn_user(f"Checkpoint is {age.days} days old")

# Check compatibility
if checkpoint["metadata"]["shannon_version"] != CURRENT_VERSION:
    warn_user("Checkpoint from different Shannon version")

# Check project
if checkpoint["project_state"]["project_id"] != current_project:
    confirm_user("Restoring different project. Continue?")

2. Prefer Auto-Selection Unless Specific Need

# Good: Let skill find best checkpoint
restore_from_latest()

# Acceptable: User has specific reason
restore_from_checkpoint("phase_2_complete_checkpoint")

# Avoid: Randomly picking old checkpoints
restore_from_checkpoint("checkpoint_from_last_week")

3. Log Restoration Events

# Create audit trail
write_memory(f"restore_log_{timestamp()}", {
    "checkpoint_used": checkpoint_id,
    "restoration_time": current_time(),
    "memories_restored": len(restored_memories),
    "success": all_valid,
    "missing_memories": missing_keys,
    "warnings": warnings
})

4. Handle Graceful Degradation

# If full restoration fails, try partial
if not restore_all_context():
    print("Full restoration failed. Attempting partial...")

    # Restore in priority order
    for priority in ["critical", "important", "optional"]:
        try:
            restore_by_priority(priority)
        except:
            continue

    print("Partial restoration complete")
    print("Some features may be unavailable")

Integration with Other Skills

With context-checkpoint

# Checkpoint saves state
checkpoint_id = context_checkpoint.create()

# Restoration loads state
context_restoration.restore(checkpoint_id)

# Round-trip preservation
assert original_state == restored_state

With spec-analysis

# If spec analysis missing after restore
if "spec_analysis" not in restored_memories:
    print("⚠️  Specification analysis not found in checkpoint")
    print("Re-running analysis...")

    # Trigger spec-analysis skill
    spec_analysis.analyze(project_path)

With wave-orchestration

# Restore wave context for continuation
wave_context = {
    "current_wave": checkpoint["project_state"]["current_wave"],
    "completed_waves": checkpoint["wave_context"]["completed_waves"],
    "pending_waves": checkpoint["wave_context"]["pending_waves"]
}

# Pass to wave orchestration
wave_orchestration.resume(wave_context)

References

• CONTEXT_MANAGEMENT.md: Core checkpoint/​restore patterns
• PreCompact Hook: Auto-checkpoint before compact
• Serena MCP: Persistent memory storage

Summary

Context restoration provides zero-downtime recovery from context loss events through:

1. Checkpoint Retrieval: Load saved state from Serena MCP
2. State Deserialization: Parse checkpoint JSON structure
3. Context Restoration: Rebuild project/​wave/​agent state
4. Validation: Ensure integrity and availability
5. Continuation: Resume from exact interruption point

Result: Users experience seamless continuation across session boundaries with complete preservation of work state.