context-restore

Context Restore

Overview

Fully restore working context when resuming after a break. Goes beyond STATUS.json to rebuild complete understanding.

Core principle: Don't just know what to do - understand why and how.

Trigger: After session-resume for Fresh Start sessions, or manual deep restore

The Restore Process

Step 1: Load STATUS.json

Read and parse the status file:

• Project name and current branch
• In-progress tasks
• Focus area and next action
• Key decisions made

Step 2: Review Git State

# See what's changed
git status

# Review recent commits for context
git log --oneline -10

# See uncommitted changes
git diff --stat

Step 3: Read Key Files

Based on focus area, read relevant files:

If working on feature:

• Main feature file(s)
• Related test files
• Recently modified files (git diff --name-only)

If debugging:

• Error-related files
• Test files that failed
• Log files if available

If refactoring:

• Files being refactored
• Files that import/use them
• Test coverage for affected areas

Step 4: Check Project State

# Run tests to verify state
npm test

# Check for lint errors
npm run lint

# Verify build passes
npm run build

Step 5: Rebuild Mental Model

Construct understanding:

## Current Context

### What We're Building

[Feature description from STATUS.json focus area]

### Where We Are

- Branch: [branch name]
- Last commit: [commit message]
- Uncommitted: [files and their purpose]

### Key Files

- `path/to/main.ts` - [what it does, current state]
- `path/to/test.ts` - [test coverage status]

### Decisions Made

- [Decision 1 from keyDecisions]
- [Decision 2]

### What's Next

1. [nextAction from STATUS.json]
2. [Logical following step]

### Potential Issues

- [Any warnings from tests/lint]
- [Any blockers noted]

Step 6: Offer Continuation

Present restored context and options:

Context fully restored. Here's where we are:

[Mental model summary]

Ready to continue. Options:
1. Proceed with: [next action]
2. Review specific file first
3. Run full test suite
4. See detailed task breakdown

What would you like to do?

Deep Restore Checklist

For complex projects or long breaks:

• STATUS.json loaded and parsed
• Git branch and status verified
• Recent commits reviewed
• Key files read and understood
• Tests run and status known
• Build verified
• Services checked
• Mental model constructed
• Next action clear

Example Restore

🔍 Full Context Restore

Loading STATUS.json...
✓ Project: my-app
✓ Branch: feature/user-auth
✓ Focus: Authentication system

Reviewing git state...
✓ Last commit: a7f3c2e - feat: add login form
✓ 2 uncommitted files:
  - src/auth/reset.ts (new)
  - src/auth/reset.test.ts (new)

Reading key files...
✓ src/auth/login.ts - Login form complete
✓ src/auth/reset.ts - Password reset in progress (50%)
✓ Tests: 45 passing, 0 failing

Mental Model:
- Building password reset flow
- Login and validation complete
- Reset flow needs: email template, token generation
- Using nodemailer (decided last session)

Next action: Add forgot password email template

Ready to continue?

When to Use

Use context-restore when:

• Fresh Start session (> 4 hours gap)
• Complex feature with many files
• Returning after distraction
• Unclear on previous state
• Need to verify decisions made

Skip context-restore when:

• Continuation session (< 30 min)
• Simple, single-file work
• Just committed everything
• Clear on what to do next

Integration

Pairs with:

• session-resume - Triggers context-restore for Fresh Start
• session-capture - Creates the STATUS.json being restored

Calls:

• Read tool to examine key files
• Bash for git commands and tests
• TodoWrite to restore task state