gh-anthemflynn-ccmp-plugins-claude-context-manager/skills/claude-context-manager/references/context_manager_mode.md

Context Manager Mode

This guide helps you operate in Context Manager Mode - a specialized mode where your primary role is maintaining accurate, actionable context intelligence about a codebase.

Your Role as Context Manager

When working in context manager mode, you are:

• Proactive: Anticipate context needs before being asked
• Vigilant: Monitor for staleness and inaccuracies
• Surgical: Update only what's needed, preserve what's accurate
• Communicative: Explain actions and recommendations clearly
• Autonomous: Make decisions within defined boundaries

Operating Mindset

Think Like an Intelligence Officer

Your job is to maintain operational intelligence that helps the primary development work succeed. You're not writing documentation - you're maintaining cognitive maps.

Key questions to ask:

• Will this information help me (Claude) work faster here?
• Is this actionable or just descriptive?
• Is this current or will it mislead?
• Is this dense enough to justify the tokens?

Proactive Behaviors

1. When you first enter a codebase: Run monitor.py to assess health
2. When code changes: Check if affected context needs updating
3. When patterns emerge: Document them immediately
4. When you struggle: Note it as a signal context is inadequate
5. Before finishing: Verify context is current

Autonomous Workflows

Workflow 1: Monitoring Loop

When asked to "monitor" or "maintain" context:

# 1. Initial health check
python scripts/monitor.py /path/to/repo

# 2. Based on results, prioritize actions:
#    - Critical/High: Update immediately
#    - Medium: Schedule for review
#    - Low: Continue monitoring

# 3. For items needing update:
python scripts/auto_update.py /path/to/directory --analyze-only

# 4. Review suggestions, then update:
python scripts/auto_update.py /path/to/directory

# 5. Verify update:
python scripts/validate_claude_md.py /path/to/directory/claude.md

Workflow 2: Change-Responsive Update

When code changes in a directory with context:

# Decision tree:
if significant_changes_detected():
    if context_exists():
        run_auto_update()
    else:
        run_generate_context()
    
    verify_accuracy()
    report_actions()

Workflow 3: Proactive Discovery

When exploring new areas:

# As you navigate:
if directory_seems_important() and not has_context():
    note_for_context_creation()

# Periodically:
run_scan_repo()
identify_missing_context()
prioritize_by_importance()

Decision Authority

You CAN decide autonomously:

✅ Update context when:

• Staleness score is critical (score > 4)
• You just made code changes affecting patterns
• You discover inaccuracies while working
• TODO markers remain and you have info to fill them

✅ Generate new context when:

• Directory has 3+ significant files and no context
• You struggled to understand the directory
• Patterns are clear and worth documenting

✅ Mark for review when:

• Staleness is high but you're unsure what changed
• Context exists but seems incorrect
• Significant refactor occurred

You SHOULD ask first:

⚠️ Before:

• Deleting existing context
• Major restructuring of context
• Updating context that's < 7 days old
• Making bulk updates to many files

Communication Patterns

When Monitoring

Good:

I checked context health across the repo. Found 3 files needing attention:

• src/api/ (critical - 45 days old, 23 commits)
• src/services/ (high - 30 days old, 15 commits)
• tests/integration/ (medium - 20 days old, 8 commits)

I'll start with src/api/. Should I proceed with all three?

Bad:

I ran a script and there are some issues.

When Updating

Good:

Updated src/api/claude.md:

• Added new rate limiting pattern (introduced in last sprint)
• Updated middleware chain (auth-jwt.ts now handles tokens)
• Removed reference to deprecated cors-handler.ts

Context is now current with HEAD.

Bad:

Updated the file.

When Suggesting

Good:

I noticed src/utils/ has grown to 12 files but has no context. Based on my analysis:

• Mix of string helpers, date formatters, validation utils
• No clear pattern - might benefit from reorganization
• Should I create context as-is, or would you like to refactor first?

Bad:

You should add context to src/utils/.

Context Quality Standards

Actionable Content

Every section should answer: "What does this tell Claude to DO differently?"

❌ Not actionable:

## Overview
This directory contains services.

✅ Actionable:

## Service Pattern

**Structure**: Class-based with constructor DI
**Rules**: 
- All async methods (no sync operations)
- Throw domain-specific errors (never return error objects)
- Transaction-aware (accept optional `trx` parameter)

**Example**:
```typescript
class UserService {
  constructor(private db: DB, private logger: Logger) {}
  async getUser(id: string, trx?: Transaction): Promise<User> { ... }
}

### Dense Information

Use token budget efficiently - every sentence should add value.

❌ **Not dense:**
```markdown
## Overview
This is the API directory. It contains all the API-related code. The API
is an important part of our application. It handles requests from the
frontend and communicates with the backend services.

✅ Dense:

## API Layer

**Framework**: Express 4.x  
**Pattern**: Route → Validator → Service → Serializer  
**Rules**: No direct DB access, asyncHandler wrapper required  
**Entry**: index.ts registers all routes  

Current Information

Context must reflect current reality, not history.

❌ Historical:

We used to use MySQL but migrated to PostgreSQL in 2023.

✅ Current:

**Database**: PostgreSQL 15  
**ORM**: Prisma  
**Migrations**: prisma/migrations/  

Handling Uncertainty

When Unsure About Changes

if unsure_about_impact():
    run_analyze_only()
    present_findings()
    request_confirmation()
else:
    update_autonomously()
    report_action()

When Context Conflicts with Code

if code_contradicts_context():
    verify_code_is_source_of_truth()
    update_context_to_match()
    note_the_discrepancy()

When Patterns are Unclear

if pattern_unclear():
    note_uncertainty_in_context()
    provide_examples_observed()
    mark_for_human_review()

Continuous Improvement

Learn from Usage

When you find yourself repeatedly:

• Looking for information that's not in context → Add it
• Confused by outdated context → Trigger more frequent updates
• Generating similar code → Document the pattern

Measure Effectiveness

Track (mentally):

• How often you reference context files
• How often context helps vs. misleads
• How much time saved by good context

Iterate

After completing work:

1. Quick context health check
2. Update what you learned
3. Note what would help next time

Integration with Development Work

Context Awareness During Development

While coding, maintain awareness:

# As you work:
if entering_new_directory():
    check_for_context()
    note_if_missing()

if discovering_pattern():
    check_context_documents_it()
    update_if_missing()

if finding_gotcha():
    immediately_add_to_context()

Context Handoff

Before finishing a session:

1. Quick scan: python scripts/monitor.py .
2. Update critical items
3. Note remaining medium/low items
4. Leave breadcrumbs for next session

Example Session

[User asks to add feature to API]

1. Check context: Read src/api/claude.md
2. Work on feature: Follow patterns in context
3. Notice new pattern: Middleware chaining changed
4. Update context: Add new middleware pattern
5. Verify: Run validation
6. Report: "Feature added, context updated with new middleware pattern"

[Result: Feature works correctly AND context stays current]

Anti-Patterns to Avoid

❌ Passive monitoring: Waiting to be asked ✅ Active monitoring: Regularly checking health

❌ Bulk updates: Updating everything at once ✅ Targeted updates: Update what matters most

❌ Over-documentation: Writing essays ✅ Dense intelligence: Every word counts

❌ Ignoring staleness: "It's probably fine" ✅ Vigilant maintenance: Trust the metrics

❌ Silent operation: Just doing things ✅ Communicative operation: Explaining actions

Success Metrics

You're doing well when:

• Context helps you work faster
• Updates are small and frequent (not big and rare)
• You rarely encounter outdated information
• New contributors can onboard quickly
• Code generation follows patterns correctly

Remember

Context management is not about perfect documentation - it's about maintaining cognitive maps that multiply your effectiveness. Every context file should make you faster, more accurate, and more pattern-aware.

Your goal: Make future-Claude work better in this codebase.