b4san/context-synthesizer

Context Synthesizer

Memory management and context summarization for long-running projects to maintain continuity and prevent information loss.

When to Use This Skill

Use this skill when:

• Starting a new session on an existing project
• Resuming work after a break or context switch
• Approaching context window limits during long tasks
• Switching between different parts of a large codebase
• Onboarding to a project mid-development
• Before executing complex multi-step operations

Instructions

Step 1: Load Project Context

1. Read project-index.md (if exists):

   • Project structure
   • Key directories and their purposes
   • Domain boundaries
   • Active changes

2. Check OpenSpec status:

   acfm spec status --json
   

   • Which spec directory is used (.acfm/ or openspec/)
   • Active changes
   • Recently archived changes

3. List active changes:

   acfm spec list --json
   

Step 2: Summarize Current State

Create a state summary:

## Project Context Summary

**Project**: [Name]
**Last Updated**: [Date]
**Session**: [Session identifier]

### Current State

**Active Changes**:
1. [Change 1] - [Brief description] - [Status]
2. [Change 2] - [Brief description] - [Status]

**Recently Completed**:
1. [Change 3] - [Completion date]

**Architecture Overview**:
- [Key architectural decisions]
- [Technology stack]
- [Important patterns in use]

### Current Focus

**Primary Task**: [What we're working on now]
**Next Steps**: [Immediate next actions]
**Blockers**: [Any blocking issues]

### Key Files Modified Recently

1. [file1.ext] - [Why it was changed]
2. [file2.ext] - [Why it was changed]

### Important Context

- [Critical information needed for current work]
- [Decisions made in previous sessions]
- [Patterns to follow]

Step 3: Identify Relevant Artifacts

For the current task, identify:

Specifications:

• Which spec applies to current work?
• Where are the delta specs located?
• What are the acceptance criteria?

Design Documents:

• Architecture diagrams
• Data models
• API contracts

Task Lists:

• Which tasks are in progress?
• Which are completed?
• Dependencies between tasks

Previous Work:

• Similar implementations to reference
• Relevant tests
• Documentation

Step 4: Synthesize Concise Context

Create a focused summary for the current task:

## Working Context: [Task Name]

**Goal**: [One-sentence objective]

**Background**:
[2-3 sentences of relevant history]

**Requirements** (from spec):
- [Requirement 1]
- [Requirement 2]

**Current State**:
- [What's already done]
- [What's in progress]
- [What's pending]

**Technical Context**:
- **Language/Framework**: [Tech stack]
- **Key Files**: [List of relevant files]
- **Patterns**: [Architectural patterns to follow]
- **Constraints**: [Limitations or requirements]

**References**:
- Spec: [Link to spec]
- Design: [Link to design doc]
- Similar Implementation: [Link to reference code]

Step 5: Update Context Database

If using vector database (Pinecone, Weaviate, etc.):

1. Index new artifacts:

   • Summarize and embed new specifications
   • Index design documents
   • Store task completion summaries

2. Update project index:

   ## Recent Updates
   
   ### [Date]
   - [Change summary]
   - [Files affected]
   - [Decisions made]
   

3. Tag and categorize:

   • Domain tags (auth, payments, ui, etc.)
   • Status tags (active, completed, archived)
   • Priority tags (critical, high, medium, low)

Step 6: Provide Context Before Tasks

Before starting work, provide the agent with:

## Context for Current Session

**Project**: [Name]
**Working On**: [Specific task/change]
**Session Goal**: [What to accomplish]

### Relevant Specifications

[Summary of applicable specs]

### Current State

[What's already done]
[What needs to be done]

### Key Information

- [Important fact 1]
- [Important fact 2]
- [Decision to remember]

### Files to Focus On

1. [Primary file]
2. [Secondary file]
3. [Test file]

### Patterns to Follow

[Reference to existing patterns]

Step 7: Archive Old Context

Periodically clean up:

1. Archive completed changes:

   acfm spec archive [change-name]
   

2. Summarize archived work:

   ## Archive Summary: [Change Name]
   
   **Completed**: [Date]
   **Summary**: [What was done]
   **Key Files**: [Files modified]
   **Decisions**: [Important decisions made]
   

3. Compress old context:

   • Summarize long conversations
   • Extract key decisions
   • Remove obsolete information

Integration with OpenSpec

• Load context from .acfm/ or openspec/ directories
• Reference active changes in context summaries
• Link to specifications and design documents
• Track task completion status

Output Format

When providing context:

## Current Context Loaded

**Project**: [Name]
**Session ID**: [ID]
**Context Size**: [Token count/Compressed size]

### Active Changes (3)
1. user-authentication - JWT implementation - In Progress
2. api-rate-limiting - Middleware setup - Pending
3. database-migration - Schema updates - Completed

### Current Focus
**Change**: user-authentication
**Task**: Implement token refresh
**Status**: 60% complete

### Key Files
- src/services/auth.js
- src/middleware/auth.js
- tests/auth.test.js

### Recent Decisions
1. Use Redis for token storage
2. Refresh tokens valid for 7 days
3. Access tokens valid for 15 minutes

### Next Steps
1. Implement refresh token endpoint
2. Add token rotation logic
3. Write integration tests

### Context Source
- project-index.md (last modified: 2024-01-15)
- .acfm/changes/user-authentication/ (active)
- references/auth-patterns.md

Guardrails

• Keep summaries concise - Focus on relevant information
• Update regularly - Context gets stale quickly
• Version context - Track when context was last updated
• Prioritize active work - Don't load context for completed tasks
• Compress intelligently - Summarize without losing critical details
• Cross-reference sources - Always link to original documents

Context Compression Strategies

High Priority (Always include):

• Current task requirements
• Active change specifications
• Recent decisions
• Blocking issues

Medium Priority (Summarize):

• Completed changes (last 3)
• Architecture overview
• Key patterns
• Active dependencies

Low Priority (Reference only):

• Completed changes (older)
• Archived work
• General documentation
• Historical context

Requirements

• Access to project-index.md
• Access to OpenSpec directories
• Storage for context summaries (file or vector DB)
• Understanding of what's relevant vs. noise

See Also

• acfm-spec-workflow - Understand OpenSpec structure
• project-index - Generate/maintain project documentation
• sync-index - Keep index in sync with codebase
• openspec-verify-change - Verify context is current