---
name: eck:fresh-context
version: "0.7.4"
description: Subagent-based context continuation when the current context window is nearing exhaustion.
disable-model-invocation: false
---

# Fresh Context

Spawn an isolated subagent with a structured handover document to continue work when the current context window is filling up. The subagent receives a clean context window containing only the handover document, allowing it to complete remaining work without the accumulated context burden of the parent session. See ADR-005 for design rationale.

---

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Task Registration

| Stage | Subject                  | Active Form        | Statusline     |
| ----- | ------------------------ | ------------------ | -------------- |
| 1     | Stage 1: Assess Context  | Assessing context  | Assess (1/4)   |
| 2     | Stage 2: Compose Handoff | Composing handoff  | Compose (2/4)  |
| 3     | Stage 3: Launch Subagent | Launching subagent | Subagent (3/4) |
| 4     | Stage 4: Report Results  | Reporting results  | Report (4/4)   |

## Usage

```
/eck:fresh-context
/eck:fresh-context "remaining task description"
```

---

## Stage 1: Assess Current State

### Inputs

- Current session history
- Optional task description argument from `$ARGUMENTS`
- Files created, modified, or committed during the session

### Activities

Gather the information needed for the handover document by reviewing the current session:

1. **Overall task goal** — What is the user trying to accomplish?
2. **Completed steps** — What has been done so far? List files created, modified, committed.
3. **Active decisions and constraints** — What decisions were made during the session? What must not change?
4. **Key file paths** — Which files are relevant to the remaining work?
5. **Open questions** — What is unresolved?
6. **Heuristics to preserve** — Any conventions, patterns, or active heuristics established in this session.

If the user provided a task description argument (e.g., `/eck:fresh-context "finish implementing the auth module"`), use it as the starting point for the task description. Otherwise, synthesize the task description from the session history.

### Outputs

- Assessed session state: goal, completed steps, decisions, key files, open questions, heuristics

### Exit Criteria

- All handover fields populated with data from current session

---

## Stage 2: Compose Handover Document

### Inputs

- Assessed session state from Stage 1

### Activities

Build the structured handover document using this template (per ADR-005):

```markdown
## Fresh Context Handover

**Original task:** {task name and brief description}
**Interrupted at:** {ISO 8601 timestamp}
**Context fill at handover:** {N}%

### What Has Been Completed

- {step 1}
- {step 2}
- {step N}

### Active Decisions and Constraints

- {decision 1: what was decided and why}
- {constraint 1: what must not change and why}

### Immediate Next Step

{single clear action the new session should take first}

### Key File Paths

| File   | Purpose   | Status                       |
| ------ | --------- | ---------------------------- |
| {path} | {purpose} | {created / modified / to-do} |

### Open Questions

- {question 1}
- {question 2}

### Heuristics to Preserve

{any active heuristics or conventions established in the current session}
```

**Populate every section.** If a section has no content (e.g., no open questions), write "None" rather than omitting the section — the subagent should know that nothing was omitted by accident.

Present the composed handover document to the user for review:

```
AskUserQuestion:
  "Here is the handover document I'll pass to the subagent. Does this look correct?"
  Options:
    - "Looks good — proceed"
    - "I want to edit it"
```

If the user wants to edit, incorporate their changes and re-present until approved.

### Outputs

- Composed handover document approved by user

### Exit Criteria

- User has confirmed the handover document is accurate

---

## Stage 3: Spawn Subagent

### Inputs

- Approved handover document from Stage 2

### Activities

**MUST** invoke the Agent tool with the approved handover document. Do NOT skip subagent dispatch or attempt to continue work inline:

```
Agent(
  description: "Continue: {task name}",
  prompt: "{full handover document}",
  subagent_type: "general-purpose"
)
```

If the Agent tool is unavailable or fails to spawn, report the error to the user and provide the handover document as copyable text so they can paste it into a new session manually:

> The Agent tool is not available in this environment. Here is the handover document — paste it as the opening message of a new Claude Code session to continue:
>
> {handover document}

### Outputs

- Subagent spawned with handover document, or handover document provided for manual use

### Exit Criteria

- Agent tool invoked with approved handover document, or fallback text provided to user

---

## Stage 4: Report Results

### Inputs

- Subagent return value (result, files changed, actions taken, errors)

### Activities

When the subagent returns, present a summary to the user:

1. **Result summary** — What the subagent accomplished.
2. **Files changed** — List of files created, modified, or deleted by the subagent.
3. **Actions taken** — Key actions beyond file changes (commits, tool invocations, etc.).
4. **Issues encountered** — Any errors, blockers, or warnings the subagent reported.

If the subagent failed or timed out:

- Report the failure clearly.
- Show what (if anything) the subagent completed before failing.
- Suggest next steps: re-run `/eck:fresh-context` with a narrower task scope, or paste the handover document into a new session manually.

### Outputs

- Summary report of subagent results displayed to user

### Exit Criteria

- User receives a clear summary of what the subagent accomplished (or failed to accomplish)

---

## Error Handling

Follow the `output:error-handler` primitive for error classification, formatting, and recovery guidance.
