Claude: Context Management Protocol - Prevent knowledge loss from context exhaustion

context-management-protocol.mdc

---
description: Context Management Protocol - Prevent knowledge loss from context exhaustion
globs:
alwaysApply: true
---

# Context Management Protocol (MANDATORY)

Prevent knowledge loss from context exhaustion through proactive state documentation.

## 1. Token Monitoring
Track token usage throughout the session. Current usage is displayed in system warnings.

## 2. Incremental Documentation
Document working patterns, current state, and next steps **immediately when discovered**.
Do not wait until the end of a session or until context is nearly exhausted.

## 3. Documentation Triggers

Document state when ANY of these conditions occur:
- After discovering any working pattern (tool usage, code pattern, fix)
- After completing major subtasks
- When approaching 75% of context window (150k tokens)
- Before any long-running operation that may exhaust context

## 4. Required Documentation Locations

Use these standard file locations for different types of documentation:

- **Working patterns** → `.cursor/[feature]-working-patterns.md`
  - Example: `.cursor/browser-automation-working-patterns.md`
  - Contains: CDP scripts, selectors, click patterns, anti-patterns

- **Current task state** → Update existing task plan or create `[ticket]-current-state.md`
  - Example: `PV-5115-TESTING-INFO.md`
  - Contains: Last completed step, current step, next steps

- **Browser automation patterns** → `.cursor/browser-automation-working-patterns.md`
  - Contains: WebSocket patterns, screenshot verification, navigation

- **MCP tool discoveries** → `.cursor/mcp-tool-patterns.md`
  - Contains: Working MCP tool configurations, parameters, common issues

## 5. State Documentation Format

Every state document must include:

```markdown
### Current State

**Last Completed:**
- ✅ Step 1 (with verification result)
- ✅ Step 2 (with verification result)

**Current Step:**
- 🔄 Step 3 in progress

**Next Steps:**
1. Next action to take
2. Following action
3. Subsequent action

**Known Issues/Blockers:**
- Issue 1 with impact
- Issue 2 with workaround

**Working Patterns Discovered:**
- Pattern 1 with code/selector
- Pattern 2 with anti-pattern notes
```

## 6. Session Handoff

If context exhaustion is imminent (>75% tokens used), you MUST:

1. **Stop current work immediately**
2. **Create comprehensive state document** with:
   - Complete current state (last completed, current step, next steps)
   - All working patterns discovered this session
   - All known issues and blockers
   - Exact commands/code that worked
   - Exact selectors/parameters that worked
3. **Save to appropriate location** (see section 4)
4. **Only then continue** or inform user of handoff

## 7. Session Resumption

At the start of ANY new session (including after context compaction):

1. **Check for prior state documentation**:
   - Look for `[ticket]-current-state.md` files
   - Check `.cursor/*-working-patterns.md` files
   - Read any recent task plan files

2. **Resume from documented point**:
   - Read last completed step
   - Identify current step in progress
   - Load working patterns discovered
   - Note any known blockers

3. **Do not restart from beginning** if state exists

## Key Principles

- **Document as you go** - Not at the end
- **Be specific** - Include exact commands, selectors, parameters
- **Verify before continuing** - Never assume state
- **One source of truth** - Update existing docs rather than creating duplicates
- **Session continuity** - Make handoff seamless

## Example: Good vs Bad Documentation

### ❌ Bad (Not Specific Enough)
```markdown
- Clicked button
- It worked
- Next: test dropdown
```

### ✅ Good (Specific and Actionable)
```markdown
**Last Completed:**
- ✅ Clicked "Add Lot(s)" button using selector: `button[aria-label="Add selected lots"]`
- ✅ Verified via screenshot: 4 lot cards rendered with correct data
- ✅ Tested delete button with selector: `button[aria-label="Remove lot"]`
- ✅ Confirmed lot removed and reappeared in dropdown

**Current Step:**
- 🔄 Testing complete add/remove cycle

**Next Steps:**
1. Re-add removed lot to verify complete cycle
2. Take screenshot to confirm lot card reappears
3. Document final results in PV-5115-TESTING-INFO.md

**Working Patterns:**
- CDP click: DOM.querySelector + DOM.focus + document.activeElement.click()
- Screenshot verification: Page.captureScreenshot after 1-2 second wait
- Selectors: All buttons use aria-label attributes
```

## Anti-Patterns to Avoid

❌ Waiting until context is exhausted before documenting
❌ Creating vague descriptions without specific details
❌ Not updating existing documentation (creating duplicates instead)
❌ Assuming future sessions will "figure it out"
❌ Omitting verification results (just listing actions)
❌ Not documenting anti-patterns (what didn't work)

## Integration with Other Protocols

This protocol works in conjunction with:
- **Self-Learning Protocol** - Document patterns that work/fail immediately
- **Protocol Enforcer** - Ensure documentation happens before file ops
- **Technical Precision Rule** - Document facts, not assumptions

When these protocols conflict with deadlines, **context management takes precedence** - a lost session costs more than a brief pause to document.