yaze/docs/internal/agents/archive/plans-2025-11/CLEANUP_SUMMARY.md

Documentation Cleanup Summary - November 2025

Date: 2025-11-24 Action: Cleanup of speculative planning documents and AI-generated bloat from /docs/internal/plans/ Rationale: Planning documents should live in GitHub issues and coordination board, not as static markdown. Only actionable, actively-tracked plans belong in the codebase.

Files Deleted (Pure AI-Generated Bloat)

These files were entirely speculative with no corresponding implementation:

1. asm-debug-prompt-engineering.md (45KB)

   • Extensive prompt templates for 65816 debugging
   • No evidence of integration or use
   • Classified as AI-generated reference material

2. ai-assisted-development-plan.md (17KB)

   • Workflow proposal for AI-assisted development
   • All features marked "Active" with "Next Review" dates but never implemented
   • Generic architecture diagrams with no corresponding code

3. app-dev-agent-tools.md (21KB)

   • 824 lines specifying 16 agent tools (build, code analysis, debug, editor integration)
   • All tools in Phase 1-3 (theoretical)
   • No implementation in codebase or recent commits

4. EDITOR_ROADMAPS_2025-11.md (25KB)

   • Multi-agent analysis document referencing "imgui-frontend-engineer" agent analysis
   • Generic roadmap format with estimated effort hours
   • Duplicate content with dungeon_editor_ui_refactor.md

5. message_system_improvement_plan.md (2KB)

   • Duplicate of sections in message_editor_implementation_roadmap.md
   • Generic feature wishlist (JSON export, translation workspace, search & replace)
   • No distinct value

6. graphics_system_improvement_plan.md (2.8KB)

   • Feature wishlist (unified editor, palette management, sprite assembly)
   • No concrete deliverables or implementation plan
   • Superseded by architecture documentation

7. ui_modernization.md (3.3KB)

   • Describes patterns already documented in CLAUDE.md
   • Marked "Active" but content is obsolete (already implemented)
   • Redundant with existing guidelines

Files Archived (Partially Implemented / Historical Reference)

These files have some value as reference but are not actively tracked work:

1. emulator-debug-api-design.md → archive/plans-2025-11/

   • Design document for emulator debugging API
   • Some features implemented (breakpoints, memory inspection)
   • Watchpoints and symbol loading still planned but deprioritized
   • Value: Technical reference for future work

2. message_editor_implementation_roadmap.md → archive/plans-2025-11/

   • References actual code (MessageData, MessagePreview classes)
   • Documents what's completed vs. what's missing (JSON import/export)
   • Some ongoing development but should be tracked in coordination board
   • Value: Implementation reference

3. hex_editor_enhancements.md → archive/plans-2025-11/

   • Phase 1 (Data Inspector) concept defined
   • Phases 2-4 unimplemented
   • Better tracked as GitHub issue than static plan
   • Value: Technical spike reference

4. dungeon_editor_ui_refactor.md → archive/plans-2025-11/

   • Actually referenced in git commit acab491a1f (component was removed)
   • Concrete refactoring steps with clear deliverables
   • Now completed/obsolete
   • Value: Historical record of refactoring

Files Retained (Actively Tracked)

1. web_port_strategy.md

   • Strategic milestone document for WASM port
   • Multiple recent commits show active ongoing work (52b1a99, 56e05bf, 206e926, etc.)
   • Clear milestones with deliverables
   • Actively referenced in CI/build processes
   • Status: KEEP - actively developed feature

2. ai-infra-improvements.md

   • Structured phase-based plan (gRPC server, emulator RPCs, breakpoints, symbols)
   • More specific than other plans with concrete files to modify
   • Tracks infrastructure gaps with file references
   • Status: KEEP - tracks ongoing infrastructure work

3. README.md

   • Directory governance and guidelines
   • Actively enforces plan organization standards
   • Status: KEEP - essential for directory management

Rationale for This Cleanup

Problem

• 14 planning files (400KB) in /docs/internal/plans/
• Most marked "Active" with forward-looking dates (Nov 25 → Dec 2)
• Little correlation with actual work in recent commits
• Directory becoming a repository of speculative AI-generated content

Solution

• Keep only plans with active ongoing work (2 files)
• Archive reference documents with partial implementation (4 files)
• Delete pure speculation and AI-generated bloat (7 files)
• Directory size reduced from 400KB to 13KB at root level

Principle

Planning belongs in GitHub issues and coordination board, not in markdown files.

Static plan documents should only exist for:

1. Strategic initiatives (like WASM web port) with active commits
2. Infrastructure work with concrete phases and file references
3. Historical reference after completion

Speculative planning should use:

• GitHub Discussions for RFCs
• Issues with labels for feature requests
• Coordination board for multi-agent work tracking

Files in Archive

docs/internal/agents/archive/plans-2025-11/
├── CLEANUP_SUMMARY.md
├── dungeon_editor_ui_refactor.md
├── emulator-debug-api-design.md
├── hex_editor_enhancements.md
└── message_editor_implementation_roadmap.md

These are available if needed as historical context but should not be referenced for active development.