clear-context

What this skill does

## Table of Contents

- [Quick Start](#quick-start)
- [When to Use](#when-to-use)
- [The Auto-Clear Pattern](#the-auto-clear-pattern)
- [Thresholds](#thresholds)
- [Auto-Clear Workflow](#auto-clear-workflow)
- [Integration with Existing Hooks](#integration-with-existing-hooks)
- [Self-Monitoring Pattern](#self-monitoring-pattern)

# Clear Context Skill

## Quick Start

When context pressure reaches critical levels (80%+), invoke this skill to:
1. Save current session state
2. Delegate continuation to a fresh subagent
3. Continue work without manual intervention

```
Skill(conserve:clear-context)
```

## When To Use

- **Proactively**: Before starting large multi-chained tasks
- **Reactively**: When context warning indicates 80%+ usage
- **Automatically**: Integrated into long-running workflows

## When NOT To Use

- Context usage is under 50% - continue working normally
- Mid-critical-operation where handoff would lose state
- **Consider "Summarize from here" first** (Claude Code 2.1.32+): Before full auto-clear,
  try partial summarization via the message selector. This compresses older context while
  preserving recent work, often sufficient to relieve pressure without a full handoff.

## The Auto-Clear Pattern

Since `/clear` requires user action, we achieve automatic context clearing without interruption through **subagent delegation**:

```
Main Agent (high context)
    ↓
    Saves state to .claude/session-state.md
    ↓
    Spawns continuation subagent (fresh context)
    ↓
    Subagent reads state, continues work
```

## Thresholds

| Level | Threshold | Action |
|-------|-----------|--------|
| WARNING | 40% | Monitor, plan optimization |
| CRITICAL | 50% | Prepare for handoff |
| EMERGENCY | 80% | **Execute auto-clear now** |

**Configuration** (environment variables):
- `CONSERVE_EMERGENCY_THRESHOLD`: Override 80% default (e.g., `0.75` for 75%)
- `CONSERVE_SESSION_STATE_PATH`: Override `.claude/session-state.md` default

## Auto-Clear Workflow

### Step 1: Assess Current State

Before triggering auto-clear, gather:
- Current task/goal description
- Progress made so far
- Key decisions and rationale
- Files being actively worked on
- Open TodoWrite items

### Step 1.5: Finalize Task List Before Handoff

**Important**: Before saving state or spawning a continuation agent, reconcile the task list:

1. **Review all tasks** via `TaskList`
2. **Mark completed tasks** as `completed` via `TaskUpdate`: do NOT leave done work as `in_progress`
3. **Record existing task IDs**: collect all task IDs (pending and in_progress) to pass in the session state so the continuation agent references them instead of creating duplicates
4. **Include task IDs in session state** under the `existing_task_ids` field (see Step 2)

This prevents the continuation agent from creating duplicate tasks.

### Step 2: Save Session State

**Important**: If `.claude/session-state.md` already exists, always Read it first before writing (Claude Code requires reading existing files before overwriting). Create the `.claude/` directory if it doesn't exist.

Write to `.claude/session-state.md` (or `$CONSERVE_SESSION_STATE_PATH`):

```markdown
# Session State Checkpoint
state_version: 1
Generated: [timestamp]
Reason: Context threshold exceeded (80%+)

## Execution Mode

**Mode**: [unattended | interactive | dangerous]
**Auto-Continue**: [true | false]
**Source Command**: [do-issue | execute-plan | etc.]
**Remaining Tasks**: [list of pending items]

> **Important**: If `auto_continue: true` or mode is `dangerous`/`unattended`,
> the continuation agent should not pause for user confirmation.
> Continue executing all remaining tasks until completion.

## Current Task
[What we're trying to accomplish]

## Progress Summary
[What's been done so far]

## Key Decisions
- Decision 1: [rationale]
- Decision 2: [rationale]

## Active Files
- path/to/file1.py - [status]
- path/to/file2.md - [status]

## Pending TodoWrite Items
- [ ] Item 1
- [ ] Item 2

## Existing Task IDs
[List task IDs from TaskList so the continuation agent can reference them
instead of creating duplicates. Example:]
- Task #1: "Implement feature X" (in_progress)
- Task #2: "Write tests for feature X" (pending)

## Continuation Instructions
[Specific next steps for the continuation agent]
```

**Execution Mode Detection**:

Before writing state, detect the execution mode:

```python
# Detect execution mode from environment/context
execution_mode = {
    "mode": "interactive",  # default
    "auto_continue": False,
    "source_command": None,
    "remaining_tasks": [],
    "dangerous_mode": False
}

# Check for dangerous/unattended mode indicators
if os.environ.get("CLAUDE_DANGEROUS_MODE") == "1":
    execution_mode["mode"] = "dangerous"
    execution_mode["auto_continue"] = True
    execution_mode["dangerous_mode"] = True
elif os.environ.get("CLAUDE_UNATTENDED") == "1":
    execution_mode["mode"] = "unattended"
    execution_mode["auto_continue"] = True

# Inherit from parent session state if exists
if parent_state and parent_state.get("execution_mode"):
    execution_mode = parent_state["execution_mode"]
```

### Step 2.5: Verify Session-State Clarity Before Handoff

A continuation agent inherits only what `session-state.md` says. If
the draft is ambiguous, the new agent starts from corrupted task
state. Before spawning, gate the handoff on the belief-clarity check
(the `belief-clarity` module of `Skill(conserve:context-optimization)`),
which asks two anchor questions against the draft state:

1. **Progress probe**: what is the current task progress: what is
   done, and what state is the task in now?
2. **Gap probe**: what information is still needed to finish: a
   bounded list of concrete open items, not generic categories.

Gate logic:

- Both answers specific and bounded: save and proceed to Step 3.
- Gap probe open-ended or progress probe hedging: append the failing
  probe's answer to `session-state.md` as explicit `Current state:`
  and `Still needed:` bullets, then re-score.
- Progress probe vague or empty: do not hand off. Confirm current
  state with the user (or `imbue:proof-of-work` in unattended mode)
  before writing state and retrying.

When `memory-palace:memory-clarity-probe` is installed, delegate the
dual-probe evaluation to it and use its "Proceed" composite as the
gate. This check is qualitative: it catches drift and omission, not
confidently-wrong state, so pair it with task-state verification for
high-stakes handoffs.

### Step 3: Spawn Continuation Agent

Use the Task tool to delegate. **Important**: Include execution mode in the task prompt:

```
Task: Continue the work from session checkpoint

Instructions:
1. Read .claude/session-state.md for full context
2. Check the "Execution Mode" section FIRST
3. If `auto_continue: true` or mode is `dangerous`/`unattended`:
   - DO NOT pause for user confirmation
   - Continue executing ALL remaining tasks until completion
   - Only stop on actual errors or when all work is done
4. **TASK LIST**: Do NOT create new tasks via TaskCreate. The parent agent
   already created the task list. Use TaskList to see existing tasks, and
   TaskUpdate to mark them in_progress/completed. Check the "Existing Task IDs"
   section in the session state for the authoritative list.
5. Verify understanding of current task and progress
6. Continue from where the previous agent left off
7. If you also approach 80% context, repeat this handoff process
   - PRESERVE the execution mode when creating your own checkpoint

The session state file contains all necessary context to continue without interruption.

**Execution mode inheritance**: Always inherit and propagate the execution
mode from the session state. If the parent was in dangerous/unattended mode,
you are also in that mode. Do not ask the user for confirmation.

**Task deduplication**: Do not create duplicate tasks. The parent has already
populated the task list. Use TaskUpdate on existing task IDs only.
```

**For batch/multi