RFC: Session Continuity - Checkpoint WIP State Before Compaction

[evansenter]

Summary

When Claude Code sessions run out of context and compact, the continuation summary loses work-in-progress state (uncommitted edits, current file/line position, error being debugged). This forces continuation sessions to re-discover context that was already known, wasting tokens and causing friction.

Problem / Motivation

Session compaction summaries capture what was done but not what was in progress:

• Uncommitted edits: If mid-way through editing a file, the specific changes and their purpose are lost
• Current position: Which file/function/line was being worked on
• Error state: What error was being debugged, what was already tried
• Todo progress: Which item in a multi-step task was active

Evidence: Workflow analysis identified 5 continuation sessions in 7 days that needed to re-discover context that was partially completed. Example: A session continued with "First task: Fix proptest_tests.rs import error" but didn't know the user was already mid-way through updating test expectations in request_tests.rs.

Context

• Discovered during: Workflow analysis after completing PR fix: Pre-install macfuse cask before brew bundle #293 in rust-genai
• Relevant files: ~/.claude/commands/work.md, potentially new ~/.claude/hooks/
• Related issues/PRs: None directly, this is a new observation

Proposed Solution

Enhance the /work workflow to checkpoint WIP state that survives compaction:

Option A: WIP State File

Create .claude/wip-state.json in the project directory:

{
  "work_id": "issue-272",
  "current_todo": "Fix dual wire format issue",
  "current_todo_status": "in_progress",
  "files_modified": ["agent_config.rs", "request_tests.rs"],
  "last_error": "test_thinking_summaries_serialization failed - expected lowercase",
  "last_action": "Edit request_tests.rs line 111",
  "checkpoint_time": "2026-01-04T20:00:00Z"
}

The /work --attach command would read this file to restore context.

Option B: Git Stash with Message

Use git stash push -m "WIP: [work:issue-272] Fixing dual wire format" to preserve uncommitted changes with context in the stash message.

Option C: Hook-Based Checkpointing

Add a pre-compaction hook (if Claude Code supports it) that writes state before context is lost.

Assumptions

Assumption	Confidence	Impact if Wrong
Continuation sessions can read project files	High	Would need alternative storage
WIP state is useful even without uncommitted code	Medium	May only help partial cases
/work workflow is the right place for this	Medium	Could be a standalone hook instead
Claude Code doesn't already have a better mechanism	Low	This RFC may be unnecessary

Open Questions

1. Does Claude Code have hooks for pre-compaction? If so, Option C is cleanest.
2. Should WIP state include actual file diffs? Would be more complete but larger.
3. How to handle multiple worktrees? Each would need its own WIP state.

Actionable Requirements

#	Requirement	Owner	Blocked By
1	Research Claude Code compaction hooks	Claude	-
2	Define WIP state schema	Claude	#1
3	Implement checkpoint writing in /work	Claude	#2
4	Implement checkpoint reading in /work --attach	Claude	#3
5	Add cleanup on /work completion	Claude	#4

Test Requirements

• Manual: Start work, let session compact, continue with /work --attach, verify context restored
• Edge cases:
  • Multiple todos in progress
  • Worktree-based parallel work
  • Work abandoned (no cleanup)

Implementation Checklist

• Research Claude Code compaction behavior and hooks
• Design WIP state schema
• Update /work to write checkpoint on todo state changes
• Update /work --attach to read and display WIP context
• Add cleanup when work completes (merge/close)
• Document in CLAUDE.md or workflow docs