Consolidate and Reorganize Monorepo Documentation

[justin808]

Summary

PR #2069 added ~25 documentation files (~200KB) with significant duplication and unclear organization. We need to consolidate, archive, and reorganize these docs for better maintainability.

See detailed analysis: PR_2069_DOCUMENTATION_ANALYSIS.md

Current Issues

1. Duplication: Multiple overlapping monorepo status/analysis documents

   • MONOREPO_MIGRATION_STATUS.md vs MONOREPO_MIGRATION_ANALYSIS.md vs MONOREPO_MERGER_PLAN.md

2. Location Confusion: Docs scattered across:

   • .claude/docs/analysis/ (25+ files)
   • analysis/monorepo/ (3 files)
   • docs/ (official docs)

3. Outdated Content: Many docs say "Phase 5 in progress" but PR Phase 5: Add Pro Node Renderer Package to workspace #2069 merged

4. Temporal Content: CI failure analysis from specific dates that should be archived

Proposed Structure

react_on_rails/
├── .claude/
│   └── docs/
│       ├── pr-splitting-strategy.md          ✅ Keep
│       ├── testing-build-scripts.md          ✅ Keep
│       ├── master-health-monitoring.md       ✅ Keep
│       ├── managing-file-paths.md            ✅ Keep
│       └── analysis/
│           ├── INDEX.md                      ✅ Keep (consolidate)
│           └── MIGRATION_QUICK_REFERENCE.md  ✅ Keep
│
├── analysis/                                  ← Technical deep dives
│   ├── rake-task-duplicate-analysis.md       ✅ Keep
│   ├── v8-crash-retry-solution.md            ✅ Keep
│   └── rspack-investigation.md               ← Move from .claude/
│
├── docs/
│   ├── MONOREPO_MERGER_PLAN.md               ✅ Keep (authoritative)
│   ├── MONOREPO_STATUS.md                    ← NEW (consolidate)
│   ├── MONOREPO_QUICK_START.md               ← NEW (developer guide)
│   ├── YALC_ALTERNATIVES.md                  ← Move from analysis/monorepo/
│   ├── phases/
│   │   ├── phase-6-ruby-restructure.md       ← Move from .claude/
│   │   └── phase-7-8-polish.md               ← Move from .claude/
│   └── archive/
│       ├── phase-5/                          ← Archive completed
│       │   ├── checklist.md
│       │   └── completion-notes.md
│       └── ci-incidents/                     ← Archive temporal
│           └── 2024-11-21-failures.md

Tasks

High Priority (Do First)

1. Update Status to Reflect Phase 5 Completion

• Update INDEX.md - mark Phase 5 complete
• Update all docs referencing "Phase 5 in progress"
• Update MONOREPO_MERGER_PLAN.md status

2. Consolidate Monorepo Status Docs

• Create docs/MONOREPO_STATUS.md (consolidated)
  • Merge best parts from:
    • analysis/monorepo/MONOREPO_MIGRATION_STATUS.md
    • .claude/docs/analysis/MONOREPO_MIGRATION_ANALYSIS.md
• Delete redundant files after consolidation
• Delete docs/MONOREPO_MERGER_PLAN_REF.md (duplicate)

3. Archive Temporal Docs

• Create docs/archive/ci-incidents/
• Move CI failure analyses:
  • CI_FAILURES_2024-11-21.md
  • CI_FIXES_APPLIED.md
  • CI_OPTIMIZATION_SUMMARY.md
• Create docs/archive/phase-5/
• Move completed phase docs:
  • PHASE_5_CHECKLIST.md
  • PHASE_5_COMPLETION_NOTES.md

Medium Priority (Do Next)

4. Move Phase Checklists to Official Docs

• Create docs/phases/ directory
• Move PHASE_6_CHECKLIST.md → docs/phases/phase-6-ruby-restructure.md
• Move PHASE_7_8_CHECKLIST.md → docs/phases/phase-7-8-polish.md

5. Apply or Delete CLAUDE.md Proposals

• Review CLAUDE_MD_UPDATES.md
• Review claude-md-improvements.md
• Apply valuable improvements to CLAUDE.md
• Delete proposal files

6. Handle GitHub Issue Docs

• Check if issue Monorepo of pro and basic #1765 is open/closed
• If open: Post github-issue-1765-update.md as comment
• If closed: Delete both update files
• Delete the markdown files (GitHub is system of record)

Low Priority (Nice to Have)

7. Create Developer Quick Start

• Create docs/MONOREPO_QUICK_START.md
• How to work in monorepo
• Common commands and workflows

8. Consolidate Meta Docs

• Merge README.md into INDEX.md
• Merge AI_AGENT_INSTRUCTIONS.md into INDEX.md
• Single entry point: INDEX.md

9. Move Technical Analyses

• Move RSPACK_IMPLEMENTATION.md → analysis/rspack-investigation.md
• All technical deep dives in root analysis/, not .claude/docs/analysis/

Files to Delete (After Consolidation/Archival)

Monorepo Status Duplicates:

• analysis/monorepo/MONOREPO_MIGRATION_STATUS.md
• analysis/monorepo/MONOREPO_MIGRATION_CHECKLIST.md
• .claude/docs/analysis/MONOREPO_MIGRATION_ANALYSIS.md
• docs/MONOREPO_MERGER_PLAN_REF.md

CI Temporal Docs (after archiving):

• .claude/docs/analysis/CI_FAILURES_2024-11-21.md
• .claude/docs/analysis/CI_FIXES_APPLIED.md
• .claude/docs/analysis/CI_OPTIMIZATION_SUMMARY.md

GitHub Issue Context:

• .claude/docs/analysis/github-issue-1765-update.md
• .claude/docs/analysis/github-issue-1765-status-update.md

Proposal Docs (after applying):

• .claude/docs/analysis/CLAUDE_MD_UPDATES.md
• .claude/docs/analysis/claude-md-improvements.md

Meta Duplication:

• .claude/docs/analysis/README.md
• .claude/docs/analysis/AI_AGENT_INSTRUCTIONS.md

Empty Directory:

• analysis/monorepo/ (after moving YALC_ALTERNATIVES to docs/)

Success Criteria

• Single source of truth for monorepo status: docs/MONOREPO_STATUS.md
• Phase checklists in docs/phases/
• Temporal docs archived in docs/archive/
• No duplicate status documents
• All docs reflect Phase 5 completion
• Clear separation: .claude/docs/ (AI context) vs docs/ (official) vs analysis/ (deep dives)

Estimated Effort

2-3 hours

Related

• Follow-up to PR Phase 5: Add Pro Node Renderer Package to workspace #2069
• Improves documentation maintainability
• Reduces confusion for contributors