skill-resume

---
name: skill-resume
description: "Pick up where you left off from a previous session — use after context resets, compaction, or new conversations"
disable-model-invocation: true
---

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.


# Session Restoration

## Overview

Restore context from a previous session and seamlessly continue the workflow where you left off.

**Core principle:** Check state → Load adaptive context → Display restoration summary → Route to appropriate action.


## When to Use

**Use this skill when user says:**
- "Resume" or "continue working"
- "Pick up where I left off"
- "What was I doing?"
- "Restore session"
- "Continue from last time"

**Do NOT use for:**
- Starting new projects (use /octo:embrace)
- Checking current status only (use /octo:status)
- Modifying state directly (use octo-state.sh)


## The Process

### Phase 0: Check Session Handoff File (v9.6.0)

#### Step 0: Check for the session handoff file

Before checking `.octo/`, look for a session handoff file. This is written automatically
by PreCompact and SessionEnd hooks and contains a human-readable summary of the last session.
It lives beside the workflow state returned by `octopus state-path`, outside the project
checkout. Older releases wrote `.octo-continue.md` into the project root instead; read that
copy only when no relocated handoff exists, and never modify, move, or delete it.

```bash
HANDOFF_FILE=""
if WORKFLOW_STATE_FILE="$(octopus state-path)" && [[ -n "$WORKFLOW_STATE_FILE" ]]; then
    HANDOFF_FILE="$(dirname "$WORKFLOW_STATE_FILE")/continue.md"
fi
if [[ -n "$HANDOFF_FILE" && -f "$HANDOFF_FILE" ]]; then
    cat "$HANDOFF_FILE"
elif [[ -f ".octo-continue.md" ]]; then
    cat ".octo-continue.md"
fi
```

**If a handoff file was found**, display its contents to the user as context. Then continue
to Phase 1 to load the full state. The handoff file provides a quick overview; `.octo/STATE.md`
provides the authoritative state. If the legacy `.octo-continue.md` was shown, tell the user it
is no longer updated and can be deleted from the project.

### Phase 1: Check Project Initialization

#### Step 1: Verify .octo/ Directory Exists

```bash
if [[ ! -d ".octo" ]]; then
    echo "No project state found"
    exit 1
fi
```

**If .octo/ does not exist but Step 0 found a handoff file**, display its contents and
offer to start a new session based on that context.

**If neither exists, display:**

```markdown
## Session Restoration Failed

**No project state found.**

There is no `.octo/` directory in this project, which means no previous session state exists.

### Get Started

Run `/octo:embrace [your project description]` to start a new project.

**Example:**
```
/octo:embrace build a REST API with user authentication
```

This will:
1. Initialize .octo/ directory with STATE.md, PROJECT.md, ROADMAP.md
2. Begin the Double Diamond workflow
3. Create session state you can resume later
```

**Stop here** - do not proceed to Phase 2.


### Phase 2: Read Current State

#### Step 1: Execute octo-state.sh read_state

```bash
./scripts/octo-state.sh read_state
```

**Expected output format:**
```
schema=2.0
last_updated=2026-02-02T10:30:00Z
current_phase=2
current_position=define-requirements
status=in_progress
```

#### Step 2: Parse State Variables

Extract these key values:
- `current_phase` - Phase number (1-4)
- `current_position` - Description of current position within phase
- `status` - Workflow status (in_progress, blocked, complete, paused, etc.)
- `last_updated` - Timestamp of last state modification


### Phase 3: Load Adaptive Context

#### Step 1: Get Context Tier (Auto Mode)

```bash
./scripts/octo-state.sh get_context_tier auto
```

This automatically selects the appropriate context tier based on current status:

| Status | Tier Selected | Context Loaded |
|--------|---------------|----------------|
| ready, planned, planning, complete, shipped | planning | STATE.md + PROJECT.md + ROADMAP.md |
| building, in_progress | execution | + phase plans + recent summaries |
| blocked, paused | execution | + phase plans + recent summaries |

#### Step 2: Store Context for Reference

The context returned includes:
- Current state details
- Project vision and requirements
- Phase-specific plans and summaries
- Codebase analysis (if brownfield project)


### Phase 4: Extract History and Blockers

#### Step 1: Read Last 3 History Entries from STATE.md

```bash
# Extract history section from STATE.md
grep -A 4 "^## History" .octo/STATE.md | tail -n 3
```

**Expected format:**
```
- [2026-02-02T10:30:00Z] Phase 2: Completed requirements review (complete)
- [2026-02-02T09:15:00Z] Phase 2: Started define phase (in_progress)
- [2026-02-01T16:45:00Z] Phase 1: Completed discovery (complete)
```

#### Step 2: Extract Blockers from STATE.md

```bash
# Extract blockers section
sed -n '/^## Blockers/,/^## /p' .octo/STATE.md | head -n -1 | tail -n +2
```

**Expected format:**
- If blockers exist: List of blocker items
- If no blockers: `(none)`

#### Step 3: Read Project Title from PROJECT.md

```bash
# Get project title (first H1)
head -n 5 .octo/PROJECT.md | grep "^# " | head -1 | sed 's/^# //'
```


### Phase 5: Display Restoration Summary

#### Step 1: Build and Display Summary

```markdown
## Session Restored

**Project:** {project_title from PROJECT.md}
**Last Active:** {last_updated from STATE.md}
**Phase:** {current_phase} - {phase_name}
**Position:** {current_position}
**Status:** {status}

### Where You Left Off

{Last 3 entries from STATE.md history}

### Current Blockers

{Blockers from STATE.md or "None"}

### Ready to Continue

{Intelligent suggestion based on status - see routing table below}
```

#### Step 2: Map Phase Number to Name

| Phase | Name |
|-------|------|
| 1 | Discover |
| 2 | Define |
| 3 | Develop |
| 4 | Deliver |


### Phase 6: Intelligent Routing

#### Step 1: Route Based on Status

| Status | Action | Message |
|--------|--------|---------|
| `in_progress` | Continue current phase | "Continue with current phase. Context loaded." |
| `blocked` | Review blockers | "Review blockers first: `/octo:issues`" |
| `complete` | Ready for next phase | "Phase complete. Ready for `/octo:ship`" |
| `paused` | Resume project | "Project paused. Resume with `/octo:embrace`" |
| `ready` | Begin workflow | "Ready to begin. Run `/octo:embrace` to start." |
| `planning` | Continue planning | "Continue planning. Use `/octo:define` to refine." |
| `building` | Continue building | "Continue implementation. Use `/octo:develop`." |
| `shipped` | Project delivered | "Project delivered! Review lessons in LESSONS.md." |
| `complete_with_gaps` | Review gaps | "Phase complete with gaps. Review ISSUES.md before proceeding." |

#### Step 2: Phase-Specific Guidance (for in_progress status)

**Phase 1 (Discover):**
```
Continue research and exploration.
- Use `/octo:research [topic]` for multi-AI research
- Use `/octo:debate [question]` for decision support
- Check `.octo/phases/phase1/` for research notes
```

**Phase 2 (Define):**
```
Continue requirements clarification.
- Use `/octo:prd` to write product requirements
- Use `/octo:define` to refine scope
- Check `.octo/phases/phase2/` for requirements docs
```

**Phase 3 (Develop):**
```
Continue implementation.
- Use `/octo:develop` to build features
- Use `/octo:tdd` for test-driven development
- Check `.octo/phases/phase3/` for implementation plan
```

**Phase 4 (Deliver):**
```
Continue validation and delivery.
- Use `/octo:deliver` for final review
- Use `/octo:security` for security audit
- Use `/octo:ship` to finalize delivery
```


## Example Outputs

### Example 1: No Project State Found

```markdown
## Session Restoration Failed

**No project state found.**

There is no `.octo/` directory in this project, which means no previous session state exists.

### Get Started

Run `/octo:embrace [your project description]` to start a new project.
```


### Example 2: Successful Restoration (In Progress)

```markdown
## Session Restored

**Project:** User Authentication System
**Last Active:** 2026-02-02T10:30:00Z
**Phase:** 2 - Define
**Position:** define-requirements
**Status:** in_progress

### Where You Left Off

- [2026-02-02T10:30:00Z] Phase 2: Started requirements review (in_progress)
- [2026-02-01T16:45:00Z] Phase 1: Completed discovery (complete)
- [2026-02-01T14:20:00Z] Phase 1: Research synthesis complete (in_progress)

### Current Blockers

None

### Ready to Continue

Continue with current phase. Context loaded.

Continue requirements clarification.
- Use `/octo:prd` to write product requirements
- Use `/octo:define` to refine scope
- Check `.octo/phases/phase2/` for requirements docs
```


### Example 3: Blocked Project Restoration

```markdown
## Session Restored

**Project:** E-commerce Platform
**Last Active:** 2026-02-01T18:00:00Z
**Phase:** 3 - Develop
**Position:** implement-payment-gateway
**Status:** blocked

### Where You Left Off

- [2026-02-01T18:00:00Z] Phase 3: Payment integration blocked (blocked)
- [2026-02-01T15:30:00Z] Phase 3: Started payment gateway integration (in_progress)
- [2026-02-01T12:00:00Z] Phase 3: Completed user auth implementation (complete)

### Current Blockers

- Missing Stripe API credentials
- Payment webhook endpoint not configured
- SSL certificate pending for payment domain

### Ready to Continue

Review blockers first: `/octo:issues`

**To unblock:**
1. Configure Stripe API credentials in environment
2. Set up webhook endpoint at /api/webhooks/stripe
3. Complete SSL certificate setup for payments subdomain
```


### Example 4: Paused Project Restoration

```markdown
## Session Restored

**Project:** Data Analytics Dashboard
**Last Active:** 2026-01-28T09:00:00Z
**Phase:** 2 - Define
**Position:** requirements-gathering
**Status:** paused

### Where You Left Off

- [2026-01-28T09:00:00Z] Phase 2: Project paused by user (paused)
- [2026-01-27T16:00:00Z] Phase 2: Stakeholder feedback pending (in_progress)
- [2026-01-27T10:00:00Z] Phase 1: Discovery complete (complete)

### Current Blockers

- Waiting for stakeholder availability

### Ready to Continue

Project paused. Resume with `/octo:embrace`

When ready to continue:
1. Review `.octo/PROJECT.md` for project context
2. Check `.octo/STATE.md` for pause reason
3. Run `/octo:embrace` to resume workflow
```


## Best Practices

### 1. Always Use octo-state.sh for State Reading

**Good:**
```bash
./scripts/octo-state.sh read_state
./scripts/octo-state.sh get_context_tier auto
```

**Poor:**
```bash
# Parse STATE.md manually
grep "Current Phase" .octo/STATE.md
```

### 2. Provide Full Context Restoration

**Good:**
- Load adaptive context tier
- Show last 3 history entries
- Display any blockers
- Give phase-specific guidance

**Poor:**
- Only show current phase
- Ignore history
- No next steps

### 3. Route Intelligently Based on Status

**Good:**
```
Status: blocked → "Review blockers first: /octo:issues"
```

**Poor:**
```
Status: blocked → "Continue working"
```


## Red Flags - Don't Do This

| Action | Why It's Wrong |
|--------|----------------|
| Skip .octo/ existence check | Will fail with confusing errors |
| Ignore blockers on resume | User won't know why they stopped |
| Restart from beginning | Loses all previous context and progress |
| Skip history display | User loses continuity of what was done |
| Use hardcoded context tier | Should adapt based on current status |


## Integration with Other Skills

### With /octo:status

```
/octo:resume → Full restoration with context
/octo:status → Quick dashboard without restoration
```

### With /octo:embrace

```
No .octo/ exists → /octo:resume suggests /octo:embrace
.octo/ exists but paused → /octo:resume suggests resuming with /octo:embrace
```

### With flow-* skills

```
User runs /octo:resume
→ Context restored
→ User continues with /octo:develop (or appropriate phase skill)
```


## Quick Reference

| User Input | Action Required |
|------------|-----------------|
| "resume" | Resolve state with `octopus state-path` → Load context → Display summary → Route |
| "continue" | Same as resume |
| "pick up where I left off" | Same as resume |
| "what was I doing" | Same as resume, emphasize history |
| "restore session" | Same as resume |


## The Bottom Line

```
Run `octopus state-path` → Read state → Load adaptive context → Show history + blockers → Route intelligently
Otherwise → User loses previous context and wastes time re-discovering where they were
```

**Never restart from beginning if state exists. Restore context, show history, route intelligently.**


## Context Recovery After Compaction

When context is cleared (compaction, plan mode exit, new session), detect and reload automatically:

```bash
# Auto-detect context loss without writing into the project checkout.
# The plugin executable resolves its own installation root on every host.
if ! WORKFLOW_STATE_FILE="$(octopus state-path)" || [[ -z "$WORKFLOW_STATE_FILE" ]]; then
    echo "Unable to resolve persistent workflow state; refusing an incomplete resume." >&2
    exit 1
fi
if [[ -f "$WORKFLOW_STATE_FILE" ]] && [[ -z "${WORKFLOW_CONTEXT_LOADED}" ]]; then
    echo "⚠️  Context was cleared — reloading from persistent state..."
    NEEDS_RESUME=true
fi
```

**What survives context clearing:**
- Host-workspace project state (decisions, context, metrics; resolve with `octopus state-path`)
- `context/*.md` beside the path returned by `octopus state-path` (phase outputs)
- Native tasks (TaskList still works)
- Git commits and WIP checkpoints
- Multi-AI synthesis files in `~/.claude-octopus/results/`

After resume completes, set `export WORKFLOW_CONTEXT_LOADED=true` to prevent duplicate reloads.

**State persists in files. Context clearing is not a problem. Files outlive memory.**