diff options
Diffstat (limited to 'doc/CONTEXT_MAINTENANCE.md')
| -rw-r--r-- | doc/CONTEXT_MAINTENANCE.md | 356 |
1 files changed, 112 insertions, 244 deletions
diff --git a/doc/CONTEXT_MAINTENANCE.md b/doc/CONTEXT_MAINTENANCE.md index c228cd7..5dbfc84 100644 --- a/doc/CONTEXT_MAINTENANCE.md +++ b/doc/CONTEXT_MAINTENANCE.md @@ -1,332 +1,200 @@ # Context Maintenance Guide -This document describes how to maintain clean, efficient context for AI agents (Claude, Gemini) working on this project. +Keep AI context focused on **actionable, current information** while archiving **historical details** for reference. -## 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?" +**Principle**: 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: +Essential for every session, 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 +- **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, common commands -- **doc/CONTRIBUTING.md** - Coding guidelines, commit policies -- **doc/AI_RULES.md** - Agent-specific rules +- **doc/HOWTO.md** - Usage instructions +- **doc/CONTRIBUTING.md** - Coding guidelines +- **doc/AI_RULES.md** - Agent rules ### Tier 3: Design Docs (Load On-Demand) -Load these only when working on specific subsystems: +Load 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 +- **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 material for understanding past decisions: +Reference for 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 +- **doc/COMPLETED.md**, **doc/HANDOFF*.md** +- **doc/*_ANALYSIS.md**, **doc/*_SUMMARY.md** --- ## 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 +### 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 -### On-Demand (When Context Feels Slow) -**Trigger**: AI responses taking longer, context bloat suspected +### 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 -**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 +### 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 --- -## 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) +## Decision Matrix: What to Archive? -### ⚠️ SUMMARIZE Before Archiving: -- Major architectural decisions (keep 2-3 line summary) -- Critical bug resolutions (keep root cause + solution) -- Performance optimizations (keep before/after metrics) +| 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 | -### ❌ NEVER Archive: -- Current task priorities -- Essential coding guidelines (CONTRIBUTING.md, AI_RULES.md) -- Quick-start instructions (README.md, HOWTO.md) -- Active architectural constraints +**Quick rule**: If >30 days old AND >50 lines of detail → Archive with 2-line summary. --- -## Red Flags (Time to Clean Up) +## Red Flags (Clean Up Now) -### File Size Red Flags: -- PROJECT_CONTEXT.md >500 lines -- TODO.md >800 lines +### File Size +- PROJECT_CONTEXT.md >500 lines (critical: >800) +- TODO.md >800 lines (critical: >1200) - 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/) +### 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/) -### Context Red Flags: +### Performance - AI responses noticeably slower - Token usage >50K on initial load -- Repeated "let me read..." for basic project info +- Repeated "let me read..." for basic 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/: +**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 -# 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" +# 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 -### 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) +| 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 Entry +### Good: Lean TODO.md ```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 +- [ ] **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 Entry +### Bad: Verbose TODO.md ```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] +- [ ] **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 Status +### Good: Lean PROJECT_CONTEXT.md ```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 +- Audio: Stable, 93% test coverage, variable tempo +- 3D: Hybrid SDF/raster, BVH acceleration ``` -### Bad: Verbose PROJECT_CONTEXT.md Status +### Bad: Verbose PROJECT_CONTEXT.md ```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] +#### 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] ``` --- -## Questions? - -If unsure whether to archive something, ask: +## Common Mistakes -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 +### ❌ 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 -When in doubt, **archive with a pointer**. Better to have clean context and occasionally load an archive than to bloat every session. +### ✅ Do: +- Preserve key insights in summaries +- Update file references after moves +- Keep audit trail (note where moved) +- Regular small cleanups (not big purges) --- -## Maintenance Checklist +## Quick Decision Test -Copy this for monthly reviews: - -```markdown -## Context Maintenance - [Month YYYY] +If unsure whether to archive: -### File Sizes (before) -- [ ] PROJECT_CONTEXT.md: ___ lines -- [ ] TODO.md: ___ lines -- [ ] Tier 1-2 total: ___ words +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 -### 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.] -``` +When in doubt, **archive with pointer**. Better clean context than bloat. --- -*Last updated: February 7, 2026* +*Last updated: February 9, 2026* |