# Tractatus Documentation Audit & Reorganization Plan
**Date**: 2025-10-11
**Purpose**: Improve UX by reducing document clutter and ensuring current, accurate information
**Objective**: World-class documentation experience with clear categorization

---

## Current State: 17 Documents (Too Many, Poorly Organized)

### Problems Identified:
1. **No categorization**: 16/17 documents have `category: none`
2. **Outdated content**: Multiple documents reference pre-Phase 5 architecture
3. **Misleading information**: Old architecture docs contradict current implementation
4. **Project tracking clutter**: Session summaries visible to public (should be archived)
5. **Poor UX**: Visitors overwhelmed with 17 documents, unclear which to read first

---

## Document-by-Document Audit

### ✅ KEEP - Core Documentation (7 documents → 5 after updates)

#### 1. **Architectural Overview & Research Status** ✅ PERFECT
- **Status**: NEW, v1.0.0, Current as of 2025-10-11
- **Category**: `reference`
- **Audience**: `general`
- **Action**: KEEP AS-IS (order: 1)
- **Rationale**: Comprehensive, current, production-ready status

#### 2. **Core Concepts of the Tractatus Framework** ⚠️ NEEDS UPDATE
- **Status**: Outdated (references 5 services, now 6)
- **Category**: `none` → should be `conceptual`
- **Audience**: `general`
- **Action**: UPDATE to reflect Phase 5 completion
- **Updates Needed**:
  - Add MongoDB persistence layer
  - Add API Memory integration
  - Update service count (5 → 6 with BlogCuration)
  - Reference architectural overview for details
- **New Order**: 2

#### 3. **Implementation Guide** ⚠️ NEEDS MAJOR UPDATE
- **Status**: Outdated (filesystem-based, pre-MongoDB)
- **Category**: `none` → should be `practical`
- **Audience**: `technical`
- **Action**: UPDATE to reflect MongoDB architecture
- **Updates Needed**:
  - MongoDB setup instructions
  - Remove filesystem references
  - Add environment variables (MONGODB_URI)
  - Update initialization code
  - Add production deployment section
- **New Order**: 3

#### 4. **Glossary of Terms** ⚠️ NEEDS UPDATE
- **Status**: Partially outdated
- **Category**: `none` → should be `reference`
- **Audience**: `general`
- **Action**: UPDATE with Phase 5 terms
- **Updates Needed**:
  - Add: MongoDB, MemoryProxy, API Memory
  - Update: Persistence mechanisms
  - Add: Hybrid architecture terms
- **New Order**: 8 (reference section)

#### 5. **Core Values and Principles** ✅ KEEP
- **Status**: Current (strategic foundation)
- **Category**: `none` → should be `conceptual`
- **Audience**: `general`
- **Action**: KEEP, update metadata only
- **New Order**: 4

#### 6. **Case Studies - Real-World LLM Failure Modes** ✅ KEEP
- **Status**: Current (examples remain valid)
- **Category**: `none` → should be `practical`
- **Audience**: `general`
- **Action**: KEEP, update metadata only
- **New Order**: 5

#### 7. **Business Case Template** ✅ KEEP
- **Status**: Current (practical tool)
- **Category**: `none` → should be `practical`
- **Audience**: `business`
- **Action**: KEEP, update metadata only
- **New Order**: 6

---

### 📦 ARCHIVE - Outdated/Misleading (5 documents)

#### 8. **Introduction to the Tractatus Framework** 📦 ARCHIVE
- **Why Archive**: Outdated architecture, contradicts current implementation
- **Problem**: References filesystem-only storage, pre-MongoDB
- **Category**: `none` → should be `archived`
- **Visibility**: `public` → `archived`
- **Note**: "See Architectural Overview for current introduction"

#### 9. **Tractatus-Based LLM Architecture for AI Safety** 📦 ARCHIVE
- **Why Archive**: Pre-Phase 5 architecture, now misleading
- **Problem**: Proposes architecture that was later replaced
- **Category**: `none` → should be `archived`
- **Note**: "Historical proposal. See Architectural Overview for implemented architecture."

#### 10. **Executive Brief: Tractatus-Based LLM Architecture** 📦 ARCHIVE
- **Why Archive**: Pre-Phase 5, outdated claims
- **Problem**: Based on old architecture
- **Category**: `none` → should be `archived`
- **Note**: "Historical brief. See Architectural Overview for current status."

#### 11. **Tractatus Framework Enforcement for Claude Code** 📦 ARCHIVE
- **Why Archive**: Development-specific, not public documentation
- **Problem**: Internal tool documentation, confusing for general audience
- **Category**: `none` → should be `archived`
- **Audience**: `technical` → `developer`
- **Note**: "Development tool documentation. See Implementation Guide for production deployment."

#### 12. **Organizational Theory Foundations** ⚠️ MAYBE ARCHIVE
- **Why Consider**: Academic, not practical for most visitors
- **Decision**: ARCHIVE (can restore if academic audience grows)
- **Category**: `none` → should be `archived`
- **Note**: "Academic foundations. See Core Concepts for practical overview."

---

### 📊 ARCHIVE - Project Tracking (5 documents)

These are valuable for project history but misleading/overwhelming for new visitors.

#### 13. **Phase 5 PoC - Session 1 Summary** 📦 ARCHIVE
- **Why Archive**: Project tracking, not end-user documentation
- **Problem**: Technical session notes, confusing for general audience
- **Category**: `none` → should be `project-tracking`
- **Visibility**: `public` → `archived`

#### 14. **Phase 5 PoC - Session 2 Summary** 📦 ARCHIVE
- **Why Archive**: Project tracking, not end-user documentation
- **Problem**: Technical session notes, confusing for general audience
- **Category**: `none` → should be `project-tracking`
- **Visibility**: `public` → `archived`

#### 15. **Research Scope: Feasibility of LLM-Integrated Tractatus** 📦 ARCHIVE
- **Why Archive**: Research proposal, not completed work
- **Problem**: Marked as "NOT COMPLETED WORK", misleading
- **Category**: `none` → should be `research-proposal`
- **Visibility**: `public` → `archived`

#### 16. **Research Topic: Concurrent Session Architecture** 📦 ARCHIVE
- **Why Archive**: Open research question, not documentation
- **Problem**: Raises questions without answers
- **Category**: `none` → should be `research-topic`
- **Visibility**: `public` → `archived`

#### 17. **Research Topic: Rule Proliferation** 📦 ARCHIVE
- **Why Archive**: Open research question, not documentation
- **Problem**: Raises questions without answers
- **Category**: `none` → should be `research-topic`
- **Visibility**: `public` → `archived`

---

## Proposed Reorganization

### Public Documentation (7 documents, well-organized)

**Getting Started** (order: 1-3)
1. Architectural Overview & Research Status (reference)
2. Core Concepts (conceptual) - UPDATED
3. Implementation Guide (practical) - UPDATED

**Framework Details** (order: 4-6)
4. Core Values and Principles (conceptual)
5. Case Studies (practical)
6. Business Case Template (practical)

**Reference** (order: 7-8)
7. Glossary of Terms (reference) - UPDATED

### Archives Section (10 documents, collapsed by default)

**Historical Architecture Proposals** (collapsed)
- Introduction to the Tractatus Framework
- Tractatus-Based LLM Architecture for AI Safety
- Executive Brief: Tractatus-Based LLM Architecture
- Organizational Theory Foundations

**Development & Tools** (collapsed)
- Tractatus Framework Enforcement for Claude Code

**Project Tracking - Phase 5 PoC** (collapsed)
- Session 1 Summary
- Session 2 Summary

**Research Proposals & Topics** (collapsed)
- Research Scope: Feasibility of LLM-Integrated Tractatus
- Research Topic: Concurrent Session Architecture
- Research Topic: Rule Proliferation

---

## Implementation Plan

### Phase 1: Create Archives Infrastructure
1. Add `visibility` field options: `public`, `archived`
2. Add `category` field options: `conceptual`, `practical`, `reference`, `archived`, `project-tracking`, `research-proposal`, `research-topic`
3. Update UI to show archived documents in collapsed section at bottom

### Phase 2: Update Current Documents
1. **Core Concepts**: Update with Phase 5 MongoDB architecture
2. **Implementation Guide**: Rewrite for MongoDB deployment
3. **Glossary**: Add Phase 5 terms (MongoDB, MemoryProxy, API Memory)

### Phase 3: Archive Outdated Documents
1. Update 10 documents with `visibility: archived`
2. Add archive notes explaining why archived
3. Set proper categories

### Phase 4: Update Metadata
1. Set proper `category` for all documents
2. Set proper `audience` (general/technical/business/developer)
3. Set proper `order` for public documents

### Phase 5: UX Testing
1. Verify docs page shows 7 main documents
2. Verify archives section collapsed by default
3. Verify clear categorization
4. Verify PDF downloads work
5. Get user feedback

---

## Success Criteria

### Before (Current State)
- ❌ 17 documents overwhelming visitors
- ❌ No clear categorization
- ❌ Outdated/contradictory information
- ❌ Project tracking mixed with public docs
- ❌ Poor UX for new visitors

### After (Target State)
- ✅ 7 focused, current documents for public
- ✅ Clear categories (Getting Started, Framework Details, Reference)
- ✅ All documents current and accurate
- ✅ 10 archived documents available but not prominent
- ✅ World-class UX: visitors know exactly where to start

---

## Maintenance Guidelines

### When to Archive a Document:
1. Superseded by newer documentation
2. References outdated architecture/implementation
3. Project tracking/research proposals (not end-user docs)
4. Creates confusion for new visitors

### When to Keep a Document:
1. Current and accurate
2. Provides unique value (case studies, templates)
3. Reference material (glossary)
4. Strategic foundation (values, principles)

### When to Update a Document:
1. Minor inaccuracies (update in place)
2. New features added (update in place)
3. Major architecture changes (create new version, archive old)

---

## Next Steps

1. **Get approval** for this reorganization plan
2. **Implement archives infrastructure** (visibility field, UI changes)
3. **Update** Core Concepts, Implementation Guide, Glossary
4. **Archive** 10 outdated documents
5. **Test** UX improvements
6. **Document** maintenance procedures

---

**Prepared by**: Claude Code
**Review Required**: John Stroh
**Estimated Effort**: 4-6 hours for full implementation