# Context Maintenance Guide

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

**Principle**: Answer "What am I working on **now**?" not "What did we do 6 months ago?"

---

## File Organization Hierarchy

### Tier 1: Critical (Always Loaded)
Essential for every session, remain lean:

- **CLAUDE.md** / **GEMINI.md** - Agent configuration (~30 lines)
- **PROJECT_CONTEXT.md** - High-level overview (~200 lines)
- **TODO.md** - Active tasks only (~300 lines)
- **README.md** - Quick start guide

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

- **doc/HOWTO.md** - Usage instructions
- **doc/CONTRIBUTING.md** - Coding guidelines
- **doc/AI_RULES.md** - Agent rules

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

- **doc/ASSET_SYSTEM.md**, **doc/BUILD.md**, **doc/3D.md**
- **doc/SPEC_EDITOR.md**, **doc/TRACKER.md**, **doc/PROCEDURAL.md**

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

- **doc/COMPLETED.md**, **doc/HANDOFF*.md**
- **doc/*_ANALYSIS.md**, **doc/*_SUMMARY.md**

---

## Maintenance Schedule

### After Major Milestone
1. Move completion notes from TODO.md to COMPLETED.md
2. Update PROJECT_CONTEXT.md "Current Status"
3. Archive detailed plans from TODO.md
4. Update "Next Up" section

### Monthly Review
1. Archive tasks completed >30 days ago
2. Remove old "Recently Completed" items
3. Move temp analysis docs to doc/
4. Verify agent configs load only Tier 1-2

### On-Demand (Context Bloat)
1. Run: `wc -w CLAUDE.md PROJECT_CONTEXT.md TODO.md`
2. Check for oversized files (>500 lines in Tier 1-2)
3. Archive verbose sections
4. Split large design docs

---

## Decision Matrix: What to Archive?

| Content Type | Action | Keep in Main Docs |
|--------------|--------|------------------|
| Completed tasks (>30 days) | ✅ Archive | 2-line summary |
| Detailed plans (>100 lines) | ✅ Archive | Goal + approach |
| Analysis of resolved issues | ✅ Archive | Root cause + solution |
| Deprecated designs | ✅ Archive | Pointer to archive |
| Major architectural decisions | ⚠️ Summarize | 3-line summary |
| Performance optimizations | ⚠️ Summarize | Before/after metrics |
| Current priorities | ❌ Keep | Full details |
| Coding guidelines | ❌ Keep | Full details |
| Active constraints | ❌ Keep | Full details |

**Quick rule**: If >30 days old AND >50 lines of detail → Archive with 2-line summary.

---

## Red Flags (Clean Up Now)

### File Size
- PROJECT_CONTEXT.md >500 lines (critical: >800)
- TODO.md >800 lines (critical: >1200)
- Any Tier 1-2 file >1000 lines

### Content
- "Recently Completed" >100 lines in PROJECT_CONTEXT.md
- TODO.md has tasks marked `[DONE]` >30 days ago
- Detailed plans (>50 lines) for completed tasks
- Analysis docs in root directory (move to doc/)

### Performance
- AI responses noticeably slower
- Token usage >50K on initial load
- Repeated "let me read..." for basic info

---

## Archiving Workflow

**Quick steps:**
1. Find content: `grep -n "\[x\].*202[0-9]" TODO.md`
2. Move to COMPLETED.md with format:
   ```markdown
   - [x] **Task Name**: Brief summary (2-3 bullets max, one-line result)
   ```
3. Replace verbose sections: `**Note**: See doc/COMPLETED.md`
4. Update agent configs if files moved
5. Verify: `grep -r "@doc/" CLAUDE.md GEMINI.md`

**File moves:**
```bash
git mv OLDFILE.md doc/OLDFILE.md
# Update CLAUDE.md/GEMINI.md references
# Update cross-references: grep -r "OLDFILE.md" *.md doc/*.md
git commit -m "docs: Move OLDFILE.md to doc/"
```

---

## Context Size Targets

| File | Optimal | Warning | Critical |
|------|---------|---------|----------|
| CLAUDE.md | <30 lines | - | - |
| PROJECT_CONTEXT.md | <300 lines | >500 | >800 |
| TODO.md | <500 lines | >800 | >1200 |
| Total Tier 1-2 | <10K words | >15K | >20K |

---

## Examples

### Good: Lean TODO.md
```markdown
- [ ] **Task #72: Audio Compression**
    - Goal: Reduce .spec sizes by 50%
    - Approach: uint16_t quantization, RLE
    - See: doc/AUDIO_COMPRESSION_PLAN.md
```

### Bad: Verbose TODO.md
```markdown
- [ ] **Task #72: Audio Compression**
    - Goal: Reduce .spec sizes by 50%
    - Background: float32 wasteful... [20 lines]
    - Step 1: Create interface
      - Define CompressorBase [100+ lines]
```

### Good: Lean PROJECT_CONTEXT.md
```markdown
### Current Status
- Audio: Stable, 93% test coverage, variable tempo
- 3D: Hybrid SDF/raster, BVH acceleration
```

### Bad: Verbose PROJECT_CONTEXT.md
```markdown
### Recently Completed
#### Audio Peak Fix (Feb 7)
- Real-Time Peak: Fixed bug where... [20 lines]
- Decay Optimization: Changed 0.95 to 0.7... [15 lines]
[200+ lines of milestones]
```

---

## Common Mistakes

### ❌ Don't:
- Archive active tasks or priorities
- Remove essential architectural context
- Break cross-references without updating
- Delete content (archive instead)
- Keep "Recently Completed" >3 months

### ✅ Do:
- Preserve key insights in summaries
- Update file references after moves
- Keep audit trail (note where moved)
- Regular small cleanups (not big purges)

---

## Quick Decision Test

If unsure whether to archive:

1. Completed >30 days ago? → Archive
2. Detailed plan (>50 lines)? → Archive (keep 2-line summary)
3. Needed next week? → Keep
4. New contributor needs immediately? → Keep

When in doubt, **archive with pointer**. Better clean context than bloat.

---

*Last updated: February 9, 2026*