From a9a151a4fdcd46f4737abe98c654c1ec619ef425 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sat, 7 Feb 2026 15:34:46 +0100
Subject: docs: Reorganize documentation with tiered hierarchy for context
 optimization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Major documentation reorganization to reduce AI agent context size by ~58%
and establish sustainable maintenance practices.

## File Moves (Root → doc/)
- Move COMPLETED.md (new), HANDOFF*.md, *_ANALYSIS.md, *_SUMMARY.md to doc/
- Keep only 5 essential files in root: CLAUDE.md, GEMINI.md, PROJECT_CONTEXT.md, TODO.md, README.md
- Result: Clean root directory with clear project essentials

## New Documentation
- doc/CONTEXT_MAINTENANCE.md: Comprehensive guide for keeping context clean
  - 4-tier hierarchy (Critical/Technical/Design/Archive)
  - Maintenance schedules (after milestones, monthly, on-demand)
  - Size targets, red flags, workflows
  - Monthly checklist template

- doc/COMPLETED.md: Historical archive of completed milestones
  - Moved "Recently Completed" sections from TODO.md and PROJECT_CONTEXT.md
  - Detailed completion history (February 4-7, 2026)
  - Frees up ~200 lines from active context

## Agent Config Updates
- CLAUDE.md: Restructured with 4-tier hierarchy
  - Tier 1: Critical (always loaded) - 3 files
  - Tier 2: Technical (always loaded) - 3 files
  - Tier 3: Design (on-demand) - 9 files
  - Tier 4: Archive (rarely) - 10 files
  - Clear usage instructions for on-demand loading

- GEMINI.md: Same tier structure + Gemini-specific state snapshot
  - Consistent with CLAUDE.md hierarchy
  - Preserved agent-specific context

## Content Optimization
- PROJECT_CONTEXT.md: Removed verbose milestones (~160 lines)
  - Replaced with concise "Current Status" summary
  - Points to COMPLETED.md for history

- TODO.md: Removed Task #51 detailed plan (~200 lines)
  - Marked Task #51 as completed
  - Kept only active/next tasks

## Impact
- Context size: 70K → 29K tokens (58% reduction)
- Root directory: 15 → 5 files (67% cleaner)
- Tier 1-2 files: 7,329 words (well under 10K target)
- Documented maintenance process for sustainability

## Files Changed
Modified: CLAUDE.md, GEMINI.md, PROJECT_CONTEXT.md, TODO.md
New: doc/COMPLETED.md, doc/CONTEXT_MAINTENANCE.md
Moved: 10 technical docs from root to doc/
---
 CLAUDE.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 61 insertions(+), 17 deletions(-)

(limited to 'CLAUDE.md')

diff --git a/CLAUDE.md b/CLAUDE.md
index cdc9e0e..f8dcd05 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,27 +1,65 @@
-# Project Context
+# ============================================
+# TIER 1: CRITICAL CONTEXT (Always Loaded)
+# ============================================
 @PROJECT_CONTEXT.md
 @TODO.md
-
-# helping and quick-start tutorials
-
 @README.md
-@doc/HOWTO.md
 
-# design docs
-@doc/ASSET_SYSTEM.md
-@doc/BUILD.md
-@doc/FETCH_DEPS.md
-@doc/3D.md
-@doc/SPEC_EDITOR.md
-@doc/TRACKER.md
-@doc/PROCEDURAL.md
-@doc/ANALYSIS_VARIABLE_TEMPO.md
-@doc/ANALYSIS_VARIABLE_TEMPO_V2.md
-
-# coding guidelines
+# ============================================
+# TIER 2: TECHNICAL REFERENCE (Always Loaded)
+# ============================================
+@doc/HOWTO.md
 @doc/CONTRIBUTING.md
 @doc/AI_RULES.md
 
+# ============================================
+# TIER 3: DESIGN DOCS (Load On-Demand)
+# ============================================
+# Load these only when working on specific subsystems:
+#
+# Audio & Tracker:
+#   @doc/SPEC_EDITOR.md - Spectral editor design
+#   @doc/TRACKER.md - Audio tracker system
+#   @doc/ANALYSIS_VARIABLE_TEMPO_V2.md - Variable tempo analysis
+#
+# 3D & Graphics:
+#   @doc/3D.md - 3D rendering architecture
+#   @doc/PROCEDURAL.md - Procedural generation
+#
+# Build & Assets:
+#   @doc/ASSET_SYSTEM.md - Asset pipeline details
+#   @doc/BUILD.md - Build system details
+#   @doc/FETCH_DEPS.md - Dependency management
+#
+# Testing & Tools:
+#   @doc/test_demo_README.md - test_demo tool documentation
+
+# ============================================
+# TIER 4: HISTORICAL ARCHIVE (Load Rarely)
+# ============================================
+# Load these only for historical context or debugging:
+#
+# Completion History:
+#   @doc/COMPLETED.md - Detailed milestone history
+#
+# Technical Investigations:
+#   @doc/GPU_EFFECTS_TEST_ANALYSIS.md
+#   @doc/PLATFORM_ANALYSIS.md
+#   @doc/PLATFORM_SIDE_QUEST_SUMMARY.md
+#   @doc/PEAK_FIX_SUMMARY.md
+#
+# Agent Handoffs:
+#   @doc/HANDOFF_CLAUDE.md
+#   @doc/HANDOFF.md
+#   @doc/HANDOFF_2026-02-04.md
+#
+# Task Tracking:
+#   @doc/TASKS_SUMMARY.md
+
+# ============================================
+# PROJECT RULES (IMPORTANT)
+# ============================================
+
 IMPORTANT:
 - Follow all rules in doc/AI_RULES.md
 - This repository is shared with Gemini-CLI
@@ -29,3 +67,9 @@ IMPORTANT:
 - Work only on tasks explicitly requested by the user
 - Do NOT modify files outside the current scope
 - Do NOT perform refactors or cleanups unless explicitly asked
+
+# Context Maintenance:
+- See @doc/CONTEXT_MAINTENANCE.md for keeping context clean
+- Archive completed work to doc/COMPLETED.md regularly
+- Keep PROJECT_CONTEXT.md focused on current status
+- Keep TODO.md focused on active/next tasks only
-- 
cgit v1.2.3