133 lines
5.3 KiB
Markdown
133 lines
5.3 KiB
Markdown
# 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.
|