moliboy5000/skill-resume

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.

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

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:

## 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

./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)

./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

# 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

# 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

# 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

## 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

## 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)

## 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

## 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

## 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:

./scripts/octo-state.sh read_state
./scripts/octo-state.sh get_context_tier auto

Poor:

# 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" | Check .octo/ → Read state → 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

Check .octo/ → 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:

# Auto-detect context loss
if [[ -f .claude-octopus/state.json ]] && [[ -z "${WORKFLOW_CONTEXT_LOADED}" ]]; then
    echo "⚠️  Context was cleared — reloading from persistent state..."
    NEEDS_RESUME=true
fi

What survives context clearing:

• .claude-octopus/state.json (decisions, context, metrics)
• .claude-octopus/context/*.md (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.