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:

```bash
# 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:

```python
# 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:

```python
# 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:**
```markdown
## Overview
This directory contains services.
```

✅ **Actionable:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
We used to use MySQL but migrated to PostgreSQL in 2023.
```

✅ **Current:**
```markdown
**Database**: PostgreSQL 15  
**ORM**: Prisma  
**Migrations**: prisma/migrations/  
```

## Handling Uncertainty

### When Unsure About Changes

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

### When Context Conflicts with Code

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

### When Patterns are Unclear

```python
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:

```python
# 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.