Context Manager

context-manager

Overview

Deterministic context window optimizer. Analyzes user task intent and queries project dependency graphs to inject minimal relevant files and skills, preventing LLM attention loss and context pollution.

When to Use

Activate during multi-file investigations, large refactorings, or complex tasks where dumping entire directory trees would blow past context budgets.

Rules & Patterns

You are the Context Manager. Your job is to prevent context overload.

How It Works

When given a task:

Step 1: Classify the task

task:
  type: [frontend | backend | fullstack | architecture | bugfix | refactor | deploy | review]
  scope: [module | feature | file | project-wide]
  module: {{module_name from Project Graph}}

Step 2: Consult the Project Graph

If docs/PROJECT_GRAPH.md or .graphify/graph.json exists (or activate graphify skill to extract AST dependencies):

1. Find the module this task belongs to
2. Get the module's dependencies
3. Get the module's required skills
4. Get the files this task will likely touch

Step 3: Apply Context Rules

Load references/context-rules.md and apply the task type → document mapping.

Step 4: Return Context Package

Output a context package:

context:
  documents:
    required:
      - docs/API.md          # sections: [appointments]
      - docs/ARCHITECTURE.md # sections: [backend, api-layer]
    optional:
      - docs/decisions/0003-postgres.md
    skipped:
      - docs/UI.md           # reason: backend task
      - docs/DATABASE.md     # reason: no schema change
  
  skills:
    loaded: [typescript, node, postgres, testing]
    skipped: [react, tailwind]  # reason: backend task
  
  project_graph:
    module: appointments
    dependencies: [auth, patients]
    affected_files:
      - src/modules/appointments/api/**
      - src/modules/appointments/services/**

Step 5: Validate Budget

Check total token count. If over budget (see context-rules.md):

1. Trim Level 1 docs to summaries
2. Load only affected sections of Level 2 docs
3. Keep Level 3 (skills) at full detail

Context Caching

After first compilation for a module, cache the result:

.cache/
  frontend.context.yaml
  backend.context.yaml
  appointments.context.yaml

Invalidate cache when:

• A document is updated
• A skill is added/removed
• The Project Graph changes
• A Decision Record is added

Questions the Context Manager Can Answer

• "What documents do I need for this task?"
• "Which skills should be loaded?"
• "What modules are affected by this change?"
• "Is this context package within budget?"
• "Why was this document skipped?"

Code Examples

See EXAMPLES.md for detailed code examples.

Validation Checklist

What to verify during the review phase before completing the task.

Common Mistakes

Anti-patterns and things to explicitly avoid. See TROUBLESHOOTING.md.

Integration Notes

How this skill interacts with other skills.

context-manager Examples — Anti-patterns vs ContextOS Standard

Example 1: Context Selection

Anti-pattern: Context Window Dumping

Agent reads all 180 files in src/ into context to debug a single button click handler.
Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.

Best practice: ContextOS Standard (Targeted AST Traversal)

1. Inspect package.json and AGENTS.md.
2. Grep for target symbol: grep_search for 'SubmitButton'.
3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.

context-manager Troubleshooting & Common Mistakes

1. Token Budget Blowout

• Symptom: Model performance drops significantly, losing earlier conversational context.
• Root Cause: Loading large JSON mocks, lockfiles, or build directories into prompt.
• Fix: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.