# Context Verification Checklist

Comprehensive checklist for validating context save/restore operations.

**Workflow**: _______________
**Date**: _______________
**Verifier**: _______________

---

## Pre-Save Validation

### Required Fields Present
- [ ] `version` - Schema version number (e.g., "1.0")
- [ ] `workflow_id` - Unique identifier
- [ ] `timestamp` - ISO 8601 format
- [ ] `current_agent` - Agent saving context
- [ ] `phase` - Current workflow phase

**Score**: ___/5 required fields

### Essential Content
- [ ] `files_modified` - All changed files listed
- [ ] `decisions` - Key decisions documented
- [ ] `pending_actions` - Next steps clear
- [ ] `context_summary` - Human-readable summary (≤500 chars)

**Score**: ___/4 essential fields

### Data Quality
- [ ] No sensitive data (API keys, passwords)
- [ ] File paths are relative (not absolute)
- [ ] Timestamp is current (within last hour)
- [ ] Workflow ID follows naming convention
- [ ] All JSON is valid and parseable

**Score**: ___/5 quality checks

---

## Context Size Optimization

### Size Metrics
- **Target**: < 100KB for 80% of workflows
- **Actual Size**: _____ KB

- [ ] Size is reasonable for workflow complexity
- [ ] No redundant data included
- [ ] Large data compressed or externalized
- [ ] Conversation history pruned if > 50 messages

### Compression Opportunities
- [ ] Remove completed `pending_actions`
- [ ] Prune old `conversation_history` entries
- [ ] Externalize large file contents
- [ ] Compress checkpoint snapshots

**Optimization Score**: ___/8

---

## Serialization Validation

### JSON Validation
- [ ] Valid JSON syntax (no trailing commas)
- [ ] All strings properly escaped
- [ ] No circular references
- [ ] Dates in ISO 8601 format
- [ ] Schema validation passes

### Schema Compliance
- [ ] Matches context-schema-template.json
- [ ] All required fields present
- [ ] Field types correct (string, array, object)
- [ ] Enum values valid
- [ ] No extra unknown fields (or documented as custom)

**Serialization Score**: ___/10

---

## Handoff Readiness

### Next Agent Preparation
- [ ] `next_agent` specified (or null if complete)
- [ ] `pending_actions` are clear and actionable
- [ ] Required files are accessible
- [ ] Dependencies are documented
- [ ] Constraints are explicit

### Context Clarity
- [ ] `context_summary` accurately describes state
- [ ] `decisions` explain rationale
- [ ] No ambiguous pending actions
- [ ] Next steps prioritized
- [ ] Exit criteria defined

**Handoff Score**: ___/10

---

## Restore Validation

### Pre-Restore Checks
- [ ] Context file exists and is readable
- [ ] JSON is valid and parseable
- [ ] Version is compatible with current schema
- [ ] Workflow ID matches expected pattern
- [ ] Timestamp is reasonable (not too old)

### Context Loading
- [ ] All required fields successfully loaded
- [ ] No parsing errors or exceptions
- [ ] Type conversion successful
- [ ] No data loss during deserialization
- [ ] Context object fully initialized

### State Reconstruction
- [ ] `files_modified` paths resolve correctly
- [ ] Referenced files still exist
- [ ] Dependencies are satisfied
- [ ] Agent can resume from this state
- [ ] No missing critical information

**Restore Score**: ___/15

---

## Workflow Continuity

### State Consistency
- [ ] Previous agent's output available
- [ ] Current phase matches workflow progression
- [ ] No gaps in decision chain
- [ ] File modifications trackable
- [ ] Error log is complete

### Resume Capability
- [ ] Agent can determine next action from context
- [ ] All tools/resources available
- [ ] No manual intervention needed
- [ ] Progress is measurable
- [ ] Completion criteria clear

**Continuity Score**: ___/10

---

## Error Handling

### Error Resilience
- [ ] Handles missing optional fields gracefully
- [ ] Validates required fields before proceeding
- [ ] Provides clear error messages
- [ ] Suggests fixes for common issues
- [ ] Has rollback mechanism

### Error Logging
- [ ] `error_log` array present (if errors occurred)
- [ ] Errors include timestamp and agent
- [ ] Resolution status tracked
- [ ] Stack traces captured (if applicable)
- [ ] Impact assessment documented

**Error Handling Score**: ___/10

---

## Security & Privacy

### Sensitive Data
- [ ] No API keys in context
- [ ] No passwords or tokens
- [ ] No personal identifiable information (PII)
- [ ] No internal URLs or IPs (if sensitive)
- [ ] Secrets referenced by ID, not value

### Access Control
- [ ] Context stored in secure location
- [ ] File permissions appropriate
- [ ] Encrypted if contains sensitive references
- [ ] Access logged for audit trail
- [ ] Retention policy defined

**Security Score**: ___/10

---

## Performance Metrics

### Save Performance
- **Target**: < 200ms for save operation
- **Actual**: _____ ms

- [ ] Save time within target
- [ ] No blocking operations
- [ ] Async save if large context
- [ ] Compression applied if needed

### Restore Performance
- **Target**: < 500ms for restore operation
- **Actual**: _____ ms

- [ ] Restore time within target
- [ ] Lazy loading for large history
- [ ] Cached if frequently accessed
- [ ] Progress indicator for slow loads

**Performance Score**: ___/8

---

## Version Compatibility

### Schema Version
- [ ] Current version documented
- [ ] Migration path from older versions
- [ ] Backward compatibility maintained
- [ ] Breaking changes documented
- [ ] Version upgrade tested

### Agent Compatibility
- [ ] Context works with current agent versions
- [ ] Deprecated fields handled
- [ ] New fields have defaults
- [ ] Agent can skip unknown fields
- [ ] Compatibility matrix documented

**Compatibility Score**: ___/10

---

## Total Score Calculation

| Category | Score | Weight | Weighted |
|----------|-------|--------|----------|
| Pre-Save Validation | ___/14 | 10% | ___ |
| Size Optimization | ___/8 | 5% | ___ |
| Serialization | ___/10 | 15% | ___ |
| Handoff Readiness | ___/10 | 15% | ___ |
| Restore Validation | ___/15 | 20% | ___ |
| Continuity | ___/10 | 15% | ___ |
| Error Handling | ___/10 | 10% | ___ |
| Security | ___/10 | 5% | ___ |
| Performance | ___/8 | 3% | ___ |
| Compatibility | ___/10 | 2% | ___ |

**Total Score**: ___/100

---

## Quality Gates

### Must Pass (Blocking)
- [ ] Total score ≥ 85
- [ ] No critical security issues
- [ ] All required fields present
- [ ] Restore test successful
- [ ] Next agent can load context

### Should Pass (Important)
- [ ] Size < 100KB
- [ ] Performance within targets
- [ ] Schema validation passes
- [ ] No errors in log

### Nice to Have
- [ ] Total score ≥ 95
- [ ] Full conversation history
- [ ] Comprehensive checkpoints
- [ ] Automated testing in place

**Gates Passed**: ___/13

---

## Checklist Results

**Context Status**: [ ] ✅ Valid / [ ] ⚠️ Needs Fixes / [ ] ❌ Invalid

**Critical Issues**: ___
**Important Issues**: ___
**Minor Issues**: ___

**Recommendation**:
[ ] Ready for handoff
[ ] Fix issues before handoff
[ ] Recreate context from scratch

---

## Common Issues & Fixes

### Issue: Context Too Large
**Symptom**: Size > 100KB
**Fix**:
- [ ] Remove completed actions
- [ ] Prune conversation history
- [ ] Externalize file contents
- [ ] Compress checkpoints

### Issue: Missing Required Fields
**Symptom**: Restore fails
**Fix**:
- [ ] Add all required fields from template
- [ ] Validate against schema
- [ ] Use context builder helper

### Issue: Sensitive Data Detected
**Symptom**: Security scan finds secrets
**Fix**:
- [ ] Remove API keys
- [ ] Redact passwords
- [ ] Reference secrets by ID
- [ ] Apply encryption if needed

### Issue: Stale Context
**Symptom**: Timestamp > 7 days old
**Fix**:
- [ ] Verify files still exist
- [ ] Validate dependencies current
- [ ] Update timestamp if still valid
- [ ] Archive if no longer needed

### Issue: Version Incompatibility
**Symptom**: Old version can't load
**Fix**:
- [ ] Run migration script
- [ ] Update to current schema
- [ ] Test with both versions
- [ ] Document breaking changes

---

## Action Items

### Immediate Fixes (if issues found)
1. [ ] Issue: _______________
   - Priority: Critical/High/Medium/Low
   - Fix: _______________
   - Owner: _______________

2. [ ] Issue: _______________
   - Priority: Critical/High/Medium/Low
   - Fix: _______________
   - Owner: _______________

### Process Improvements
- [ ] Update context template
- [ ] Add validation scripts
- [ ] Improve documentation
- [ ] Create migration tools

---

## Sign-off

**Verified By**: ___________
**Date**: ___________
**Status**: [ ] Approved / [ ] Conditionally Approved / [ ] Rejected

**Notes**:
_____________________________________________
_____________________________________________

---

## Quick Reference

**Minimum Valid Context:**
```json
{
  "version": "1.0",
  "workflow_id": "workflow-name",
  "timestamp": "2025-01-15T10:00:00Z",
  "current_agent": "agent-name",
  "phase": "phase-name"
}
```

**Typical Size Ranges:**
- Small: 5-20 KB
- Medium: 20-100 KB
- Large: 100-500 KB
- Very Large: 500KB+ (needs optimization)

**Critical Fields:**
- ✅ version, workflow_id, timestamp
- ✅ current_agent, phase
- ⚠️ next_agent, pending_actions
- ℹ️ context_summary

---

**Checklist Version**: 1.0
**Last Updated**: 2025-01-15