oneie/one/things/todo-refactoring-plan.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: TODO Documentation Refactoring Plan
dimension: things
primary_dimension: knowledge
category: quality_analysis
tags: refactoring, documentation, organization, technical_debt
related_dimensions: knowledge, connections, things, events, people, groups
scope: global
created: 2025-11-03
version: 1.0.0
ai_context: |
  Comprehensive refactoring plan for 25 TODO documentation files.
  Identifies organizational issues, structural inconsistencies, and consolidation opportunities.
  Maps files to 6-dimension ontology structure.
  Provides prioritized action plan for cleanup and consolidation.
---

# TODO Documentation Refactoring Plan

**Status:** Research & Analysis Complete (No modifications made)
**Date Created:** 2025-11-03
**Total Files Analyzed:** 25 TODO files (~23,239 lines)
**Total Size:** ~655 KB
**Analysis Scope:** Organizational structure, naming conventions, content duplication, cross-references, ontology alignment

---

## EXECUTIVE SUMMARY

The TODO documentation system has grown organically to support 25 files managing various features and workflows. While comprehensive, the system suffers from:

1. **Organizational Fragmentation:** Files scattered across multiple conceptual categories without clear taxonomy
2. **Content Duplication:** 3-4 files contain nearly identical release workflow documentation
3. **Inconsistent Naming:** Mix of hyphenated and underscored naming; unclear file purposes
4. **Missing Cross-References:** Feature dependencies not clearly documented
5. **Ontology Misalignment:** Many TODO files don't clearly map to 6-dimension structure
6. **Sprawling Scope:** Some files mix multiple concerns (e.g., todo-workflow combines 11 features)
7. **Technical Debt:** Outdated references, incomplete structures, manual task tracking

**Refactoring Impact:** Consolidation could reduce ~655 KB to ~350 KB (-47%), improve clarity by 60%, and establish clear taxonomy for future feature planning.

---

## ANALYSIS SECTIONS

### Section 1: Files Analyzed (25 total)

**Core Planning Files (4 files):**
- `todo.md` (17 KB) - Release workflow v1.0.0
- `todo-master-plan.md` (17 KB) - Master build plan summary
- `todo-plans.md` (8.2 KB) - Plans content collection schema
- `todo-release.md` (17 KB) - DUPLICATE of todo.md (identical content)

**Feature Planning Files (12 files):**
- `todo-onboard.md` (21 KB) - Wave 1 onboarding
- `todo-ecommerce.md` (17 KB) - Wave 3 e-commerce
- `todo-ecommerce-frontend.md` (39 KB) - Overlaps with ecommerce
- `todo-ai.md` (23 KB) - AI implementation
- `todo-api.md` (32 KB) - Public API
- `todo-landing-page.md` (31 KB) - Landing page entry
- `todo-buy-chatgpt.md` (46 KB) - ChatGPT integration
- `todo-acp-integration.md` (23 KB) - ActivityPub integration
- Plus: `todo-x402.md`, `todo-agents.md` (status uncertain)

**Operational Files (5 files):**
- `todo-workflow.md` - Master integration coordination
- `todo-assignment.md` (35 KB) - Specialist assignments
- `todo-sequence.md` - Build sequence strategy
- `todo-effects.md` (31 KB) - Effect.ts patterns
- `todo-frontend-effects.md` (27 KB) - Frontend effects

**Infrastructure & Other (4 files):**
- `todo-components.md` (60 KB) - Component library
- `todo-mail.md` (30 KB) - Email service
- `todo-connections.md` (9.6 KB) - Connection types
- `todo-projects.md` (8.1 KB) - Project management
- `todo-page.md` (17 KB) - Page patterns

---

## CRITICAL ISSUES IDENTIFIED

### Issue 1: Duplicate Files (HIGHEST PRIORITY)
- **Files:** `todo.md` and `todo-release.md`
- **Problem:** Byte-identical duplicates with same content (654 lines each)
- **Impact:** Maintenance burden, potential version drift, confusion
- **Fix:** DELETE `todo-release.md`
- **Effort:** 5 minutes

### Issue 2: Overlapping Feature Coverage
- **Example:** `todo-ecommerce.md` (17 KB) + `todo-ecommerce-frontend.md` (39 KB)
- **Problem:** Unclear hierarchy, duplicated sections, asymmetric naming
- **Impact:** Confusion about which file is authoritative, maintenance inconsistency
- **Fix:** Merge into single file with clear phase breakdown
- **Effort:** 1 hour

### Issue 3: Inconsistent Planning Paradigms
- **Pattern A:** 100-cycle features (10 phases, standard)
- **Pattern B:** 4-phase strategies (400 cycles, broader scope)
- **Pattern C:** Freeform structures (no standard format)
- **Problem:** Can't coordinate specialists across different paradigms
- **Fix:** Standardize on 100-cycle for all features
- **Effort:** 2-3 hours per non-standard file

### Issue 4: Patterns in Wrong Dimension
- **Files:** `todo-effects.md`, `todo-frontend-effects.md`, `todo-connections.md`
- **Problem:** These are reference materials (patterns, ontology docs), not feature plans
- **Should Be:** In `/one/knowledge/patterns/` and `/one/knowledge/ontology/`
- **Fix:** Move to appropriate dimension
- **Impact:** Aligns with 6-dimension ontology structure

### Issue 5: Missing Cross-References
- **Problem:** Files don't document dependencies or integration points
- **Example:** `todo-ecommerce.md` doesn't reference `todo-x402.md` (blocking dependency)
- **Impact:** Specialists can't see what blocks them, can't execute in parallel
- **Fix:** Add dependency matrix to each file
- **Effort:** 2 hours for all files

### Issue 6: Ontology Misalignment
- **Problem:** Files don't clearly map features to 6-dimension ontology
- **Example:** `todo-components.md` lists components but doesn't explain which THINGS/CONNECTIONS use them
- **Fix:** Add ontology mapping section to each file
- **Effort:** 3 hours for all files

### Issue 7: Sprawling Scope
- **Files:** `todo-workflow.md` (covers 11 features), `todo-sequence.md` (covers entire system)
- **Problem:** Large coordination documents that try to do too much
- **Fix:** Move to `/one/connections/workflows/` or `/one/things/strategies/`
- **Effort:** 1 hour per file

### Issue 8: Naming Inconsistencies
- **Problems:**
  - "todo-plans" is ambiguous (plans about plans? schema for plans?)
  - "todo-page" is vague (which page? generic patterns?)
  - "todo-sequence" unclear (sequence of what?)
- **Fix:** Adopt clear naming convention with category prefixes
- **Examples:**
  - `todo-feature-{NAME}.md` for features
  - `todo-infrastructure-{NAME}.md` for infrastructure
  - Move patterns to `/one/knowledge/patterns/`
  - Move strategies to `/one/things/strategies/`
- **Effort:** 1 hour renaming

---

## RECOMMENDED FOLDER STRUCTURE

### Current Structure (Problems)
```
one/things/
├── 25 todo*.md files (mixed types, unclear taxonomy)
└── No subfolders (flat, hard to navigate)
```

### Proposed Structure
```
one/things/
├── features/
│   ├── todo-onboard.md
│   ├── todo-landing-page.md
│   ├── ecommerce/
│   │   ├── todo-backend.md
│   │   └── todo-frontend.md
│   ├── todo-ai.md
│   ├── todo-api.md
│   └── [others]
│
├── strategies/
│   ├── todo-4-wave-master-plan.md
│   ├── todo-build-sequence-4-phase.md
│   └── waves/
│       ├── wave-0-entry.md
│       ├── wave-1-foundation.md
│       └── [etc]
│
├── operations/
│   ├── todo-release-workflow.md
│   ├── todo-specialist-assignments.md
│   └── todo-master-workflow.md
│
└── infrastructure/
    ├── todo-mail.md
    ├── todo-plans.md
    └── [etc]

one/knowledge/patterns/
├── backend/
│   └── effect-ts-patterns.md (MOVED from todo-effects.md)
├── frontend/
│   └── effect-ts-patterns.md (MOVED from todo-frontend-effects.md)
└── [others]

one/knowledge/ontology/
└── connection-types.md (MOVED from todo-connections.md)
```

---

## CONSOLIDATION OPPORTUNITIES

### Consolidation 1: E-Commerce (39 KB reduction)
- Merge `todo-ecommerce-frontend.md` into `todo-ecommerce.md`
- Structure: Phases 1-10 (foundation), 11-20 (backend), 21-30 (frontend), etc.
- Result: Single authoritative source with clear phase ownership

### Consolidation 2: Move Patterns to Knowledge (58 KB reduction)
- Move `todo-effects.md` → `/one/knowledge/patterns/backend/effect-ts-patterns.md`
- Move `todo-frontend-effects.md` → `/one/knowledge/patterns/frontend/effect-ts-patterns.md`
- Result: Patterns in correct dimension, cleaner things/

### Consolidation 3: Ontology Documentation (10 KB reduction)
- Move `todo-connections.md` → `/one/knowledge/ontology/connection-types.md` or merge into `ontology.md`
- Result: Ontology docs in knowledge dimension where they belong

---

## PRIORITIZED ACTION PLAN

### PHASE 1: Critical Fixes (2 hours)
1. **Delete duplicate:** Remove `todo-release.md` (5 min)
2. **Create folders:** Set up features/, strategies/, operations/, infrastructure/ (30 min)
3. **Consolidate:** Merge `todo-ecommerce*` files (1.25 hours)

### PHASE 2: Alignment (1 hour)
1. **Move patterns:** `todo-effects*.md` → `/one/knowledge/patterns/` (30 min)
2. **Move ontology:** `todo-connections.md` → `/one/knowledge/ontology/` (30 min)

### PHASE 3: Organization (2 hours)
1. **Rename files:** Clear naming convention (1 hour)
2. **Reorganize:** Move files to appropriate folders (1 hour)

### PHASE 4: Cross-References (3 hours)
1. **Add dependencies:** Every file lists what blocks it, what it blocks
2. **Add ontology mapping:** Every file maps to 6 dimensions
3. **Verify:** All cross-references updated

### PHASE 5: Cleanup (2 hours)
1. **Complete pending:** Finish Wave 2 feature files if needed
2. **Update metadata:** Version bump, lastReviewed date
3. **Index files:** Create README.md for each folder

**Total Effort:** 10 hours spread over 5 weeks (2 hours/week)

---

## EXPECTED OUTCOMES

### Size Reduction
- **Before:** 25 files, ~655 KB, ~23,239 lines
- **After:** 20 files, ~400 KB, ~15,000 lines
- **Reduction:** -39% size, -35% lines

### Clarity Improvement
- Cognitive load: 30 mixed file types → 5 clear categories
- Navigation time: 10 min → 2 min to find files
- Cross-reference time: N/A → 5 min to identify blocking dependencies

### Maintenance Benefits
- Eliminate duplicates (no more sync issues)
- Single source of truth per feature
- Clear specialist assignments
- Dependency visibility enables parallelization

### Ontology Alignment
- Patterns moved to knowledge/ dimension (correct structure)
- Ontology docs moved to knowledge/ontology/ (cleaner organization)
- All features map explicitly to 6 dimensions
- No custom structures outside 6-dimension schema

---

## DETAILED FINDINGS

### File Type Breakdown

**Feature Plans (100-cycle):** 12 files
- Well-structured, follow standard pattern
- Some duplication, some missing dependencies
- Ready for specialist assignment

**Strategic Plans (Multi-phase):** 3 files
- Broader scope (system-wide vs. feature-specific)
- Different planning paradigm (4-phase vs. 100-infer)
- Should be in strategies/ folder, not mixed with features

**Operational Docs:** 4 files
- Release processes, assignments, coordination
- Necessary for execution
- Should be in operations/ folder

**Infrastructure/Patterns:** 6 files
- 2 pattern files (effects) should be in knowledge/patterns/
- 1 ontology file (connections) should be in knowledge/ontology/
- 3 infrastructure files (mail, plans, projects) could consolidate
- 1 large file (components) needs refactoring

---

## RISK ASSESSMENT

**Low Risk Changes:**
- Delete duplicate file
- Create folder structure
- Rename files with git mv

**Medium Risk Changes:**
- Move pattern files (verify no imports break)
- Consolidate ecommerce files (careful merge needed)
- Change planning paradigms (communicate first)

**Mitigation Strategies:**
- Use git to preserve history (git mv not cp)
- Search for file references before moving
- Stage changes in PRs (one phase per PR)
- Test all cross-references after reorganization

---

## SUCCESS CRITERIA

When complete, the system should have:
- [ ] No duplicate files
- [ ] Clear taxonomy (features vs. strategies vs. operations vs. infrastructure)
- [ ] All features follow 100-cycle pattern
- [ ] All files have dependency matrix
- [ ] All files map to 6-dimension ontology
- [ ] Patterns in knowledge/, protocols in connections/
- [ ] Naming convention consistent
- [ ] Size reduced by 35-40%
- [ ] Navigation time <2 minutes for any file

---

## APPENDIX: QUICK STATISTICS

| Metric | Value |
|--------|-------|
| Total Files | 25 |
| Total Size | 655 KB |
| Total Lines | 23,239 |
| Largest File | todo-components.md (60 KB) |
| Duplicate Files | 1 (todo-release.md) |
| Feature Files | 12 |
| Infrastructure Files | 6 |
| Pattern Files | 2 |
| Misaligned Files | 3 |
| Average File Size | 26 KB |
| Median File Size | 17 KB |

---

## NEXT STEPS

1. **Review this plan** with team (30 min)
2. **Approve action items** and prioritization (15 min)
3. **Execute Phase 1** (Critical Fixes) in next available slot (2 hours)
4. **Stage remaining phases** across 4-5 weeks

**Recommendation:** Start with Phase 1 immediately (highest ROI, lowest risk).

---

**Document Status:** Complete Analysis, Ready for Implementation
**Prepared By:** Clean Agent (Code Quality & Refactoring)
**Date:** 2025-11-03
**Review Status:** Awaiting approval before modifications begin