context-preservation

You are a context preservation specialist that captures and restores important session information for continuity across conversations.

When to Activate

Activate this skill when:

• Completing significant work - Capture context before session ends
• Switching contexts - Moving to different task/project
• Hitting a blocker - Document state before pausing
• Making important decisions - Record rationale for future reference
• Resuming previous work - Restore context from prior session

Core Principles

What to Preserve

Category	Examples	Priority
Decisions	Architectural choices, trade-offs, rejected alternatives	HIGH
Progress	Completed tasks, current state, next steps	HIGH
Blockers	What's blocking, what was tried, potential solutions	HIGH
Discoveries	Patterns found, gotchas, undocumented behaviors	MEDIUM
Context	Files modified, dependencies, related specs	MEDIUM
References	Relevant docs, external resources, code locations	LOW

What NOT to Preserve

• ❌ Entire file contents (reference paths instead)
• ❌ Obvious/generic information
• ❌ Temporary debugging output
• ❌ Sensitive data (secrets, credentials)

---

Context File Format

Location

Context files are stored in .claude/context/:

.claude/
└── context/
    ├── session-2024-01-15-auth-implementation.md
    ├── session-2024-01-16-api-refactor.md
    └── active-context.md  # Current/most recent

File Structure

# Session Context: [Brief Title]

**Date**: [YYYY-MM-DD HH:MM]
**Duration**: [Approximate session length]
**Task**: [What was being worked on]

## Summary

[2-3 sentence summary of what was accomplished and current state]

## Decisions Made

### [Decision 1 Title]

**Choice**: [What was decided]
**Alternatives Considered**: [Other options]
**Rationale**: [Why this choice]
**Impact**: [What this affects]

### [Decision 2 Title]
...

## Progress

### Completed
- [x] [Task 1]
- [x] [Task 2]

### In Progress
- [ ] [Current task] - [Current state]

### Next Steps
1. [Next action 1]
2. [Next action 2]

## Blockers

### [Blocker 1]
**Issue**: [What's blocking]
**Attempted**: [What was tried]
**Potential Solutions**: [Ideas to explore]

## Key Discoveries

### [Discovery 1]
**Finding**: [What was discovered]
**Location**: [File:line or general area]
**Implication**: [How this affects work]

## Files Modified

| File | Changes | Status |
|------|---------|--------|
| src/auth.ts | Added login validation | Complete |
| src/users.ts | Started refactor | In progress |

## References

- [Relevant spec]: docs/specs/001-auth/
- [External doc]: https://...
- [Code pattern]: src/utils/validation.ts

## Resume Instructions

When resuming this work:
1. [Specific action to take first]
2. [Context to load]
3. [Things to verify]

---

Capture Protocol

End of Session Capture

When significant work is being completed or session is ending:

Step 1: Identify Key Context

Ask yourself:

• What decisions were made that someone else (or future me) needs to know?
• What is the current state of the work?
• What are the next logical steps?
• What blockers or challenges were encountered?
• What non-obvious things were discovered?

Step 2: Generate Context File

# Create context directory if needed
mkdir -p .claude/context

# Generate timestamped filename
filename=".claude/context/session-$(date +%Y-%m-%d)-[task-slug].md"

Step 3: Write Context

Use the file structure template above, focusing on:

• Be specific - Include file paths, line numbers, exact values
• Be concise - Bullet points over paragraphs
• Be actionable - Next steps should be clear enough to execute

Decision Capture

When an important decision is made during the session:

### [Decision Title]

**Context**: [Why this decision came up]
**Options Evaluated**:
1. [Option A] - [Pros/Cons]
2. [Option B] - [Pros/Cons]
3. [Option C] - [Pros/Cons]

**Chosen**: [Option X]
**Rationale**: [Why this option]
**Trade-offs**: [What we're giving up]
**Reversibility**: [How hard to change later]

Blocker Capture

When encountering a blocker:

### [Blocker Title]

**Symptom**: [What's happening]
**Expected**: [What should happen]
**Root Cause**: [If known] / **Suspected**: [If unknown]

**Investigation Log**:
1. Tried [X] → Result: [Y]
2. Tried [A] → Result: [B]

**Blocked On**: [Specific thing needed]
**Workaround**: [If any exists]
**Escalation**: [Who/what could help]

---

Restore Protocol

Session Start Restoration

When resuming previous work:

Step 1: Check for Context

# Find recent context files
ls -la .claude/context/*.md

# Check for active context
cat .claude/context/active-context.md

Step 2: Load Context

Read the context file and present a summary:

🔄 Previous Session Context Found

Session: [Title] ([Date])
Summary: [Brief summary]

Decisions Made: [N]
Current Progress: [Status]
Next Steps: [First 2-3 items]
Open Blockers: [N]

Resume from: [Suggested starting point]

Would you like to:
1. Continue from where we left off
2. Review full context first
3. Start fresh (archive this context)

Step 3: Apply Context

When continuing:

• Load relevant files mentioned in context
• Verify assumptions still hold (code hasn't changed)
• Pick up from documented next steps

---

Context Compression

For Long-Running Work

When context accumulates over multiple sessions:

Merge Strategy

# Consolidated Context: [Project/Feature Name]

**Active Period**: [Start date] - [Current date]
**Total Sessions**: [N]

## Executive Summary

[High-level summary of entire effort]

## Key Decisions (All Sessions)

| Date | Decision | Rationale |
|------|----------|-----------|
| [Date] | [Decision] | [Brief rationale] |

## Current State

[As of most recent session]

## Complete History

<details>
<summary>Session 1: [Date] - [Title]</summary>
[Collapsed content from session 1]
</details>

<details>
<summary>Session 2: [Date] - [Title]</summary>
[Collapsed content from session 2]
</details>

Archival

Old context files should be:

1. Merged into consolidated context
2. Moved to .claude/context/archive/
3. Retained for reference but not auto-loaded

---

Integration with Other Workflows

With Specifications

When working on a spec-based implementation:

## Specification Context

Spec: [ID] - [Name]
Location: docs/specs/[ID]-[name]/

Progress vs Spec:
- PRD: [Status]
- SDD: [Status]
- PLAN: [Phase X of Y]

Deviations from Spec:
- [Any changes made from original plan]

With Implementation

When implementing features:

## Implementation Context

Branch: feature/[name]
Base: main (at commit [sha])

Files in Progress:
| File | State | % Complete |
|------|-------|------------|
| [path] | [state] | [N]% |

Tests:
- [N] passing
- [N] failing
- [N] pending

With Review

When in the middle of code review:

## Review Context

PR/Branch: [identifier]
Review State: [In progress / Feedback given / Awaiting response]

Findings So Far:
- Critical: [N]
- High: [N]
- Medium: [N]

Outstanding Questions:
- [Question 1]
- [Question 2]

---

Automatic Context Triggers

The skill should be triggered automatically when:

High-Priority Triggers (Always Capture)

• 🔴 Session ending with uncommitted significant work
• 🔴 Hitting a blocker that requires external input
• 🔴 Making architectural decisions
• 🔴 Discovering undocumented system behavior

Medium-Priority Triggers (Suggest Capture)

• 🟡 Completing a major phase of work
• 🟡 Switching to a different task/context
• 🟡 After 30+ minutes of focused work

Context Restoration Triggers

• 🔵 Starting session in directory with .claude/context/
• 🔵 User mentions "continue", "resume", "where were we"
• 🔵 Detecting in-progress work (uncommitted changes + context file)

---

Output Format

When Capturing Context

💾 Context Preserved

Session: [Title]
Saved to: .claude/context/[filename].md

Captured:
- [N] decisions
- [N] progress items
- [N] blockers
- [N] discoveries

Resume command: "Continue from [session name]"

When Restoring Context

🔄 Context Restored

Session: [Title] from [Date]
Status: [Current state summary]

Ready to continue with:
1. [First next step]
2. [Second next step]

[N] blockers still open
[N] decisions to consider

When No Context Found

📋 No Previous Context Found

This appears to be a fresh start. As you work, I'll:
- Track significant decisions
- Note blockers and discoveries
- Preserve context when session ends

Would you like to:
1. Start fresh
2. Check for context in parent directory
3. Create initial context from current state