[BUG] /clear breaks session continuity - --resume cannot find post-clear sessions despite official recommendation

Environment

• Claude CLI version: Claude Code 2.0.13 (reproduced across versions)
• OS: macOS
• Terminal: Various (iTerm2, Terminal.app, VSCode integrated terminal)

Summary

Following official best practices to use /clear for task separation results in permanent data loss when combined with --resume. This creates a fundamental contradiction between recommended usage and actual behavior.

Problem Description

Official Recommendation (from docs):

"Use /clear frequently, especially between different tasks" "Clear after completing a specific task"

Actual Behavior:
Using /clear as recommended breaks session continuity, making --resume unable to find any work done after /clear.

Reproduction Steps

Timeline

1. Day 1 - Evening:

``bash
claude
# Work on Task A (build up context)
# Complete Task A
/clear # Following official recommendation
# Start Task B (build new context)
# Continue working on Task B
``

1. Day 1 - Late night:

• Terminal crashes (or close terminal for the day)

1. Day 2 - Morning:

``bash
claude --resume
``

1. Result:

• ❌ Only restores Task A context (before /clear)
• ❌ Task B context (after /clear) is permanently lost
• ✅ Expected: Restore Task B (most recent work)

Expected vs Actual

| Aspect | Expected | Actual |
|--------|----------|--------|
| /clear purpose | Clear memory, maintain session chain | Break session chain permanently |
| --resume target | Most recent session | Session before last /clear |
| Data persistence | All sessions recoverable | Post-/clear sessions orphaned |
| Official guidance | Use /clear between tasks | Using /clear causes data loss |

Impact

User Experience

• Total productivity loss - Hours of work vanish permanently
• Trust breakdown - Following official advice causes harm
• Workflow disruption - Cannot safely manage long-running projects

Business Logic Contradiction

Official docs say: Use /clear to separate tasks
Actual result: /clear makes task continuation impossible
→ Users must choose: Follow advice OR keep data

Current Workaround

# Before any /clear operation:
# 1. Manually copy entire conversation to file
# 2. If crash occurs:
#    - Start new session
#    - Paste or read saved context

Why this is problematic:

• Manual, error-prone process
• Defeats purpose of session management
• No automation possible

Technical Analysis

Based on investigation:

1. /clear creates new session without parent linkage
2. --resume only finds primary session chain
3. Post-/clear sessions become "orphaned islands"

Relationship to Existing Issues

• Not covered by #1340: That issue is marked resolved
• Different from #3138: Focuses on usage limits, not /clear command
• Related to #4629: Both expose /clear implementation flaws, but different symptoms
• #4629: Context "returns" (memory leak)
• This issue: Context "disappears" (chain break)

Proposed Solutions

Short-term

1. Update documentation to warn about /clear + --resume incompatibility
2. Recommend claude --new instead of /clear for task separation

Long-term

1. Session chaining: /clear should create linked child session
2. Smart resume: --resume should traverse entire session graph
3. Session metadata: Track /clear operations with recovery hints

Why This Matters

This issue highlights a fundamental design flaw:

• Core feature (/clear) breaks core feature (--resume)
• Official guidance leads to data loss
• No warning or documentation about this limitation

Users deserve either:

• A. Working /clear that preserves session continuity, OR
• B. Clear warnings that /clear will break --resume

Currently we have neither.

Additional Context

Multiple users likely experience this silently because:

• They follow official best practices
• Terminal crashes are common
• Data loss only discovered when trying to resume
• Many may not realize --resume should work

This bug may have much wider impact than apparent from issue reports.