skill-resume

What this skill does

> **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 .octo-continue.md

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.

```bash
if [[ -f ".octo-continue.md" ]]; then
    cat ".octo-continue.md"
fi
```

**If `.octo-continue.md` exists**, read it and 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.

### 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 `.octo-continue.md` exists**, display the handoff file
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

#