path: root/doc/CONTEXT_MAINTENANCE.md

# Context Maintenance Guide

This document describes how to maintain clean, efficient context for AI agents (Claude, Gemini) working on this project.

## Philosophy

**Goal**: Keep AI context focused on **actionable, current information** while archiving **historical details** for reference.

**Principle**: The context should answer "What am I working on **now**?" not "What did we do 6 months ago?"

---

## File Organization Hierarchy

### Tier 1: Critical (Always Loaded)
These files are essential for every session and should remain lean:

- **CLAUDE.md** / **GEMINI.md** - Agent configuration (keep to ~30 lines)
- **PROJECT_CONTEXT.md** - High-level project overview (keep to ~200 lines)
  - Current status summary (not detailed milestones)
  - Architectural overview (brief)
  - Next priorities (not detailed plans)
- **TODO.md** - Active tasks only (keep to ~300 lines)
  - Current and next tasks
  - Brief attack plans (not 200-line implementation details)
  - Mark completed tasks and reference COMPLETED.md
- **README.md** - Quick start guide

### Tier 2: Technical Reference (Always Loaded)
Essential for daily work:

- **doc/HOWTO.md** - Usage instructions, common commands
- **doc/CONTRIBUTING.md** - Coding guidelines, commit policies
- **doc/AI_RULES.md** - Agent-specific rules

### Tier 3: Design Docs (Load On-Demand)
Load these only when working on specific subsystems:

- **doc/ASSET_SYSTEM.md** - Asset pipeline details
- **doc/BUILD.md** - Build system details
- **doc/3D.md** - 3D rendering architecture
- **doc/SPEC_EDITOR.md** - Spectral editor design
- **doc/TRACKER.md** - Audio tracker system
- **doc/PROCEDURAL.md** - Procedural generation
- **doc/ANALYSIS_VARIABLE_TEMPO_V2.md** - Tempo system analysis

### Tier 4: Historical Archive (Load Rarely)
Reference material for understanding past decisions:

- **doc/COMPLETED.md** - Detailed completion history
- **doc/HANDOFF*.md** - Agent handoff documents
- **doc/*_ANALYSIS.md** - Technical investigations
- **doc/*_SUMMARY.md** - Task/feature summaries

---

## Maintenance Schedule

### After Major Milestone (Immediately)
**Trigger**: Completed a multi-week task or significant feature

**Actions**:
1. ✅ Move detailed completion notes from TODO.md to COMPLETED.md
2. ✅ Update PROJECT_CONTEXT.md "Current Status" (remove old "Recently Completed")
3. ✅ Archive detailed implementation plans from TODO.md
4. ✅ Update "Next Up" section in PROJECT_CONTEXT.md

**Time**: 10-15 minutes

### Monthly Review (1st of Month)
**Trigger**: Calendar-based

**Actions**:
1. ✅ Archive tasks completed >30 days ago from TODO.md → COMPLETED.md
2. ✅ Review PROJECT_CONTEXT.md for outdated "Recently Completed" items
3. ✅ Check for temporary analysis docs in root directory → move to doc/
4. ✅ Verify CLAUDE.md/GEMINI.md only load Tier 1-2 files by default

**Time**: 15-20 minutes

### On-Demand (When Context Feels Slow)
**Trigger**: AI responses taking longer, context bloat suspected

**Actions**:
1. ✅ Run token analysis: `wc -w CLAUDE.md PROJECT_CONTEXT.md TODO.md doc/*.md | sort -rn`
2. ✅ Check for oversized files (>500 lines in Tier 1-2)
3. ✅ Aggressively archive verbose sections
4. ✅ Consider splitting large design docs

**Time**: 30-45 minutes

---

## What to Archive

### ✅ ALWAYS Archive:
- Detailed implementation plans for completed tasks (>100 lines)
- Verbose milestone descriptions with step-by-step breakdowns
- Analysis documents for resolved issues
- Deprecated design docs (keep note in main doc pointing to archive)
- Old handoff documents (>1 month old)

### ⚠️ SUMMARIZE Before Archiving:
- Major architectural decisions (keep 2-3 line summary)
- Critical bug resolutions (keep root cause + solution)
- Performance optimizations (keep before/after metrics)

### ❌ NEVER Archive:
- Current task priorities
- Essential coding guidelines (CONTRIBUTING.md, AI_RULES.md)
- Quick-start instructions (README.md, HOWTO.md)
- Active architectural constraints

---

## Red Flags (Time to Clean Up)

### File Size Red Flags:
- PROJECT_CONTEXT.md >500 lines
- TODO.md >800 lines
- Any Tier 1-2 file >1000 lines

### Content Red Flags:
- "Recently Completed" section >100 lines in PROJECT_CONTEXT.md
- TODO.md contains tasks marked `[DONE]` for >30 days
- Detailed implementation plans (>50 lines) for completed tasks in TODO.md
- Analysis documents in root directory (should be in doc/)

### Context Red Flags:
- AI responses noticeably slower
- Token usage >50K on initial load
- Repeated "let me read..." for basic project info

---

## Archiving Workflow

### 1. Identify Content to Archive
```bash
# Find large files
find . -name "*.md" -type f -exec wc -l {} + | sort -rn | head -10

# Find old completed tasks in TODO.md
grep -n "\[x\].*202[0-9]-[0-9][0-9]-[0-9][0-9]" TODO.md
```

### 2. Move to COMPLETED.md
```markdown
## Recently Completed (YYYY-MM-DD)

- [x] **Task Name**: Brief summary
  - Key points (2-3 bullets max)
  - Result: One-line outcome
```

### 3. Update Source Files
- Replace verbose sections with: `**Note**: Detailed history in doc/COMPLETED.md`
- Update cross-references
- Keep high-level summaries

### 4. Update Agent Configs
Update CLAUDE.md and GEMINI.md if files moved:
```markdown
# Design docs (load on-demand when needed)
# Use: "read @doc/COMPLETED.md" for detailed history
```

### 5. Verify
```bash
# Check context size
cat CLAUDE.md PROJECT_CONTEXT.md TODO.md | wc -w
# Target: <10,000 words for Tier 1 files

# Verify no broken references
grep -r "@doc/" CLAUDE.md GEMINI.md PROJECT_CONTEXT.md TODO.md
```

---

## Common Mistakes to Avoid

### ❌ Don't:
- Archive current priorities or active tasks
- Remove essential architectural context
- Break cross-references without updating
- Move files without updating CLAUDE.md/GEMINI.md
- Delete content (archive instead)
- Keep outdated "Recently Completed" sections >3 months

### ✅ Do:
- Preserve key technical insights (in summaries)
- Update file references after moving docs
- Keep audit trail (note where content moved)
- Maintain searchable keywords (for finding archives)
- Regular small cleanups (better than big purges)

---

## Quick Reference: File Moves

When moving files from root to doc/:

```bash
# 1. Move file (use git mv if tracked)
git mv OLDFILE.md doc/OLDFILE.md

# 2. Update CLAUDE.md
# Change: @OLDFILE.md
# To: # Use: "read @doc/OLDFILE.md" when needed

# 3. Update GEMINI.md (same as above)

# 4. Update cross-references in other files
grep -r "OLDFILE.md" *.md doc/*.md

# 5. Commit with clear message
git commit -m "docs: Move OLDFILE.md to doc/ for better organization"
```

---

## Context Size Targets

### Optimal Targets:
- **CLAUDE.md**: <30 lines
- **PROJECT_CONTEXT.md**: <300 lines
- **TODO.md**: <500 lines
- **Total Tier 1-2**: <10,000 words (~40K tokens)

### Warning Thresholds:
- **PROJECT_CONTEXT.md**: >500 lines
- **TODO.md**: >800 lines
- **Total Tier 1-2**: >15,000 words (~60K tokens)

### Critical (Clean Up Immediately):
- **PROJECT_CONTEXT.md**: >800 lines
- **TODO.md**: >1200 lines
- **Total Tier 1-2**: >20,000 words (~80K tokens)

---

## Examples

### Good: Lean TODO.md Entry
```markdown
- [ ] **Task #72: Implement Audio Compression**
    - Goal: Reduce .spec file sizes by 50%
    - Approach: Quantize to uint16_t, use RLE encoding
    - See: doc/AUDIO_COMPRESSION_PLAN.md for details
```

### Bad: Verbose TODO.md Entry
```markdown
- [ ] **Task #72: Implement Audio Compression**
    - Goal: Reduce .spec file sizes by 50%
    - Background: Currently using float32 which is wasteful...
    - Research: Investigated 5 compression algorithms...
    - Step 1: Create compression interface
      - Define CompressorBase class
      - Add compress() and decompress() methods
      - Implement factory pattern for algorithm selection
    - Step 2: Implement RLE compressor
      - [100+ more lines of detailed implementation]
```

### Good: Lean PROJECT_CONTEXT.md Status
```markdown
### Current Status
- Audio: Stable, 93% test coverage, variable tempo support
- 3D: Hybrid SDF/raster, BVH acceleration, physics system
- Shaders: Modular WGSL, comprehensive compilation tests
```

### Bad: Verbose PROJECT_CONTEXT.md Status
```markdown
### Recently Completed

#### Audio Peak Measurement (February 7, 2026)
- **Real-Time Peak Fix**: Fixed critical bug where... [20 lines]
- **Peak Decay Optimization**: Changed decay from 0.95 to 0.7... [15 lines]
- **SilentBackend**: Created test backend with... [25 lines]
- [200+ more lines of detailed milestones]
```

---

## Questions?

If unsure whether to archive something, ask:

1. **Is this about work completed >30 days ago?** → Archive
2. **Is this a detailed implementation plan?** → Archive (keep 2-line summary)
3. **Is this needed for next week's work?** → Keep
4. **Is this >50 lines of historical detail?** → Archive
5. **Would a new contributor need this immediately?** → Keep if yes

When in doubt, **archive with a pointer**. Better to have clean context and occasionally load an archive than to bloat every session.

---

## Maintenance Checklist

Copy this for monthly reviews:

```markdown
## Context Maintenance - [Month YYYY]

### File Sizes (before)
- [ ] PROJECT_CONTEXT.md: ___ lines
- [ ] TODO.md: ___ lines
- [ ] Tier 1-2 total: ___ words

### Actions Taken
- [ ] Archived tasks >30 days old to COMPLETED.md
- [ ] Moved temp analysis docs to doc/
- [ ] Updated PROJECT_CONTEXT.md current status
- [ ] Simplified TODO.md task descriptions
- [ ] Verified CLAUDE.md/GEMINI.md config
- [ ] Updated cross-references

### File Sizes (after)
- [ ] PROJECT_CONTEXT.md: ___ lines (target: <300)
- [ ] TODO.md: ___ lines (target: <500)
- [ ] Tier 1-2 total: ___ words (target: <10K)

### Notes
[Any issues encountered, files moved, etc.]
```

---

*Last updated: February 7, 2026*