Skip to main content

Document Reorganization Plan

Generated: 2025-12-28 Based on: MoE Classification Results (Phase 3.1) Status: Ready for Execution

Executive Summary​

This plan reorganizes 74 documents from legacy numbered directories (00-master-planning/, 01-architecture/) into a structured taxonomy based on MoE classification results.

Classification Results Summary​

  • Total Documents: 74
  • Approved Classifications: 6 (8.1%)
  • Escalated (Needs Review): 68 (91.9%)
  • Classification Types: ADR (37), Reference (37)

Workflow Checklist​

  • Prerequisites verified
  • Configuration applied
  • Process executed
  • Results validated
  • Documentation updated

Workflow Steps​

  1. Initialize - Set up the environment
  2. Configure - Apply settings
  3. Execute - Run the process
  4. Validate - Check results
  5. Complete - Finalize workflow

Current Directory Structure (Before)​

docs/
├── 00-master-planning/     # 18 files - legacy project planning
├── 01-architecture/        # 38 files - legacy architecture docs
├── architecture/           # 4 files - existing architecture
├── project-management/     # 7 files - existing project mgmt
├── reports/               # 3 files - existing reports
├── research/              # 5 files - existing research
└── coditect-docs-*/       # 14 files - blog/training/legal

Target Directory Structure (After)​

docs/
├── adrs/                  # Architecture Decision Records
│   ├── approved/          # High-confidence ADRs (≥60%)
│   └── pending-review/    # Low-confidence ADRs (<60%)
├── architecture/          # Architecture documentation
│   ├── design/           # System design docs
│   └── analysis/         # Analysis and research
├── project-management/    # Project documentation
│   ├── planning/         # Planning documents
│   └── reviews/          # Review documents
├── reference/            # Reference documentation
│   ├── approved/         # High-confidence refs (≥60%)
│   └── pending-review/   # Low-confidence refs (<60%)
└── [existing dirs]       # Keep existing organized directories

Reorganization Rules​

Rule 1: Classification-Based Routing​

ClassificationConfidenceTarget Directory
ADR≥60%docs/adrs/approved/
ADR<60%docs/adrs/pending-review/
Reference≥60%docs/reference/approved/
Reference<60%docs/reference/pending-review/

Rule 2: Path-Based Inference​

When classification confidence is low, use source path hints:

  • Files from 01-architecture/ → Prefer architecture/ target
  • Files named ADR-* or containing "Decision" → adrs/
  • Files named *-analysis.md → architecture/analysis/
  • Files with date patterns → project-management/reviews/

Rule 3: Conflict Resolution​

  1. Check if target file exists
  2. If conflict: append timestamp suffix _YYYYMMDD
  3. Log all conflicts in reorganization report

High-Confidence Files (Auto-Migrate)​

These 3 files have ≥60% confidence and can be automatically migrated:

FileClassificationConfidenceTarget
architecture/adr-019-moe-document-classification-system.mdADR76.8%adrs/approved/
architecture/adr-018-agentic-documentation-standard.mdADR76.2%adrs/approved/
architecture/moe-consensus-algorithm.mdADR60.0%adrs/approved/

Low-Confidence Files (Review Required)​

71 files have <60% confidence and should be:

  1. Migrated to pending-review/ subdirectories
  2. Flagged for human review
  3. Re-classified after content update

Sample Escalated Files:​

From 00-master-planning/ (18 files):​

  • 000.0000_project-review_2024-11-14_2300.md → project-management/reviews/
  • 000.0002_assumptions-analysis.md → architecture/analysis/
  • 000.04_functional-requirements.md → reference/pending-review/
  • 000.05_business-case.md → reference/pending-review/

From 01-architecture/ (38 files):​

  • 001-claude-app.py-code-analysis.md → architecture/analysis/
  • 009_database-schema.md → architecture/design/
  • 023_arch-design-part1.md → architecture/design/
  • 032_arch-design-references-part1.md → reference/pending-review/

Execution Plan​

Phase 1: Create Directory Structure​

mkdir -p docs/adrs/{approved,pending-review}
mkdir -p docs/architecture/{design,analysis}
mkdir -p docs/project-management/{planning,reviews}
mkdir -p docs/reference/{approved,pending-review}

Phase 2: Auto-Migrate High-Confidence Files​

Automatically move 3 files with ≥60% confidence.

Phase 3: Route Low-Confidence Files​

Move 71 files to appropriate pending-review/ directories.

Phase 4: Generate Migration Report​

Create detailed report of all moves with:

  • Source path
  • Target path
  • Classification reason
  • Confidence score
  • Review flag

Phase 5: Cleanup Empty Directories​

Remove empty 00-master-planning/ and 01-architecture/ after migration.

Post-Migration Actions​

  1. Review Pending Files: Human review of files in pending-review/ directories
  2. Update Cross-References: Fix any broken links between documents
  3. Re-classify: Run MoE classifier on updated documents
  4. Archive Old Backups: Move .backups/ content to cold storage

Risk Assessment​

RiskImpactMitigation
Broken linksMediumGenerate link-check report post-migration
Lost filesHighBackup before migration
Wrong classificationLowpending-review directories preserve context
Merge conflictsLowTimestamp suffix for conflicts

Rollback Plan​

If issues occur:

# Restore from backup
./scripts/reorganize-docs.py --rollback

# Or manually restore from .backups/
cp -r .backups/YYYYMMDD_HHMMSS/* docs/

Next Step: Execute scripts/reorganize-docs.py to perform migration