context-restore
Use when you need to fully restore working context from a previous session - loads STATUS.json, reads key files, rebuilds mental model of current work state. Do NOT use for quick questions or when starting fresh unrelated work - the full context restoration adds overhead that isn't needed for standalone tasks.
When & Why to Use This Skill
This Claude skill enables seamless continuity in complex projects by fully restoring the AI's working context from previous sessions. It systematically parses project status files, analyzes Git history, and reviews key source files to rebuild a comprehensive mental model of the current work state, ensuring the agent understands not just the 'what,' but the 'why' and 'how' of the task at hand.
Use Cases
- Resuming complex software development tasks after a long break or shift change to ensure no logic or requirements are missed.
- Onboarding an AI agent into an ongoing project by rebuilding its understanding of recent commits, uncommitted changes, and architectural decisions.
- Recovering from session timeouts or distractions by automatically re-verifying the project's build state, test results, and pending actions.
- Synchronizing work state across different sessions using standardized STATUS.json files to maintain a consistent 'source of truth' for the project's progress.
| name | context-restore |
|---|---|
| description | "Use when you need to fully restore working context from a previous session - loads STATUS.json, reads key files, rebuilds mental model of current work state. Do NOT use for quick questions or when starting fresh unrelated work - the full context restoration adds overhead that isn't needed for standalone tasks." |
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