From 1a323a8cd1b040ad17988a62c89e0ad84da54f79 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 2 Jun 2026 18:45:01 -0400 Subject: [PATCH] docs(track): docs layer gap analysis for comprehensive refresh --- .../gap_analysis.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md diff --git a/conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md b/conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md new file mode 100644 index 00000000..aad1b57f --- /dev/null +++ b/conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md @@ -0,0 +1,118 @@ +# Docs Layer Gap Analysis + +**Date:** 2026-06-02 +**Source of truth for features:** `conductor/product.md`, `src/` directory listing +**Source of truth for guides:** `docs/Readme.md` and `docs/guide_*.md` + +This analysis drives the Sub-Track 1 work in the parent track `documentation_refresh_comprehensive_20260602`. + +--- + +## Existing Guides and Their Coverage + +| Guide | Lines | Covers | Does NOT cover (gaps) | +|---|---|---|---| +| `docs/guide_architecture.md` | 824 | Threading model, events, AI client, HITL Execution Clutch, MMA Engine architecture, MCP allowlist, comms logging, telemetry, state machines | RAG integration with event system, Beads lifecycle hooks, Hot Reload interaction with threading model, Command Palette rendering details, NERV theme FX | +| `docs/guide_mma.md` | 470 | 4-tier MMA, Ticket/Track data structures, DAG engine, WorkerPool, ConductorEngine, Tier 2 ticket generation, Tier 3 worker lifecycle, Tier 4 QA, abort propagation, pause/resume, model escalation | Persona assignment to tiers, RAG-augmented worker context, Beads-backed track state, Hot Reload interaction with worker spawning, workspace profile auto-switching | +| `docs/guide_tools.md` | 489 | MCP Bridge 3-layer security, 26 native tools, Hook API endpoints, ApiHookClient, shell runner, parallel tool execution, session logging | New RAG tools, new Beads tools, new persona tools, new structural file editor tools, new cost tracker tools | +| `docs/guide_simulations.md` | 395 | `live_gui` fixture, Puppeteer pattern (8 stages), mock provider strategy, visual verification, supporting analysis modules | Extended simulations (RAG, Beads, Hot Reload), async tool tests, discussion metrics tests, structural file editor tests, command palette tests | +| `docs/guide_context_curation.md` | 273 | Granular AST control, fuzzy anchor slices, interactive AST tree masking, batch operations, context snapshotting, aggregation pipeline | Updates for new view modes (None, Outline, Sliced), updates for new Structural File Editor (unified AST inspector + slice editor), view presets | +| `docs/guide_shaders_and_window.md` | 33 | Hybrid shader injection (ImDrawList + PyOpenGL FBO), pure ImGui borderless window, event metrics integration | NERV theme shader effects, CRT scanline implementation, status flickering, pywin32-specific code | +| `docs/guide_meta_boundary.md` | 41 | Application domain vs Meta-Tooling domain, inter-domain bridges, `mcp_client.py` overlap, guidelines for future tiers | Whether `claude_mma_exec.py` is still in active use, whether `cli_tool_bridge.py` is still relevant, OpenCode and Gemini CLI superpowers/skills as meta-tooling | + +--- + +## Subsystems Without Dedicated Guides + +These subsystems are explicitly listed in `conductor/product.md` (or implied by major modules in `src/`) but lack dedicated guides: + +| Subsystem | Primary module | Size | Recommendation | +|---|---|---|---| +| RAG | `src/rag_engine.py` | 10.9K | NEW: `docs/guide_rag.md` — substantial module, complex algorithms (vector store, chunking strategies, multi-provider search, ChromaDB integration) | +| Beads | `src/beads_client.py` | 2.7K | NEW: `docs/guide_beads.md` — Dolt integration, JSON-RPC protocol, `bd` CLI interaction, context compaction | +| Hot Reload | `src/hot_reloader.py` | 2.2K | NEW: `docs/guide_hot_reload.md` — state-preserving module reloading, UI delegation pattern, Ctrl+Alt+R trigger, error tint feedback | +| Personas | `src/personas.py` | 4.6K | NEW: `docs/guide_personas.md` — unified profile model, MMA tier assignment, tool bias integration, persona editor modal | +| NERV Theme | `src/theme_nerv.py`, `src/theme_nerv_fx.py` | 3K + 3.8K | NEW: `docs/guide_nerv_theme.md` — Black Void palette, CRT scanline implementation, status flickering, alert animations | +| Workspace Profiles | `src/workspace_manager.py` | 2.9K | NEW: `docs/guide_workspace_profiles.md` — docking layouts, named profiles, global/project scope inheritance, contextual auto-switch | +| Command Palette | `src/gui_2.py` (relevant section) | embedded | NEW: `docs/guide_command_palette.md` OR include in `guide_architecture.md` (Async Context Preview, fuzzy command resolution) | +| Discussion Metrics & Compression | `src/ai_client.py` (relevant section) | embedded | INCLUDE in `guide_architecture.md` rewrite — per-response token tracking, history compression strategy | +| Structural File Editor | `src/gui_2.py` (relevant section) | embedded | INCLUDE in `guide_context_curation.md` rewrite — unified AST inspector + slice editor | +| Tree-sitter (Lua, GDScript, C#) | `src/mcp_client.py` (planned) | planned | OUT OF SCOPE — these are in the backlog, not yet implemented | + +--- + +## Existing Guides That Are Stale + +| Guide | Last meaningful update | Stale sections (to rewrite) | +|---|---|---| +| `docs/guide_architecture.md` | Likely Feb 2026 (last doc refresh) | "MMA Engine Architecture" section (WorkerPool + ConductorEngine) — does not include persona assignment, RAG integration, Beads hooks, Hot Reload. "AI Client: Multi-Provider Architecture" section — does not include MiniMax provider. "Anthropic Cache Strategy" — needs verification against current implementation. | +| `docs/guide_mma.md` | Likely Feb 2026 | "Tier 3: Worker Lifecycle" — does not cover RAG-augmented context, persona-driven prompt construction, Beads track state. "ConductorEngine" — does not cover workspace profile auto-switching. | +| `docs/guide_tools.md` | Likely Feb 2026 | "Native Tool Inventory" — current count is uncertain. Need to verify each tool is documented. New tools likely missing. | +| `docs/guide_simulations.md` | Likely Feb 2026 | "Puppeteer Pattern" — may not include new test stages for RAG, Beads, Hot Reload. | +| `docs/guide_context_curation.md` | Likely May 2026 (Phase 6 tracks) | Mostly current. Verify against latest Phase 6 implementation. | +| `docs/guide_shaders_and_window.md` | Likely Feb 2026 | "Custom Shaders and Window Frame Architecture" — does not include NERV theme. | +| `docs/guide_meta_boundary.md` | Likely Feb 2026 | "Meta-Tooling" section — does not include `.gemini/skills/`, `.opencode/skills/`, or `mma-orchestrator/SKILL.md`. | + +--- + +## Cross-Cutting Issues + +- **Files in `docs/MMA_Support/*` not linked from `docs/Readme.md`:** All 12 files. They're legacy MMA reference docs from a previous architecture. Decision: keep as a "Legacy MMA Reference (Deprecated)" section at the bottom of the index. + +- **Guides that reference each other via broken links:** None found in the initial scan. Will re-verify during each per-file rewrite. + +- **Symbols in docs that don't match current source:** Will be caught by symbol parity spot-checks during each rewrite. + +- **Tech-stack drift:** `guide_architecture.md` mentions "Gemini API, Anthropic API, DeepSeek" but the project now also has MiniMax. Update needed. + +- **Provider model names:** `guide_architecture.md` may have stale model names (e.g., `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash-lite` are mentioned in `conductor/tech-stack.md`; verify they're documented in the architecture guide). + +--- + +## Recommended Task Order (for Sub-Track 1) + +1. **Task 1 (this analysis)** — done +2. **Task 2: Update `docs/Readme.md`** — link previously-unlinked guides, add legacy MMA section, add new guide placeholder rows +3. **Task 3: Rewrite `docs/guide_architecture.md`** — main architecture guide +4. **Task 4: Rewrite `docs/guide_mma.md`** — MMA guide +5. **Task 5: Rewrite `docs/guide_tools.md`** — tools guide +6. **Task 6: Rewrite `docs/guide_simulations.md`** — simulations guide +7. **Task 7: Refresh `guide_context_curation.md` and `guide_shaders_and_window.md`** — in parallel since they're independent +8. **Task 8: Refresh `docs/guide_meta_boundary.md`** — small file, do after the others +9. **Task 9: Update `Readme.md`** — after all guides are updated, so the new Subsystem Index is accurate +10. **Task 10: Write new guides** — RAG, Beads, Hot Reload, Personas, NERV Theme, Workspace Profiles, Command Palette. Per-guide atomic commits. +11. **Task 11: Verification** — cross-link audit, symbol parity, subsystem coverage, Phase Completion checkpoint + +--- + +## Estimated Effort + +| Task | Estimated commits | Estimated time (single agent) | +|---|---|---| +| Task 1: Gap analysis | 1 | done | +| Task 2: docs/Readme.md | 1 | 15-30 min | +| Task 3: guide_architecture.md | 1 | 1-2 hours (largest file, most subsystems) | +| Task 4: guide_mma.md | 1 | 45-60 min | +| Task 5: guide_tools.md | 1 | 1-1.5 hours (26+ tools to document) | +| Task 6: guide_simulations.md | 1 | 45-60 min | +| Task 7: guide_context_curation.md + guide_shaders_and_window.md | 2 | 30-45 min | +| Task 8: guide_meta_boundary.md | 1 | 15-30 min | +| Task 9: Readme.md | 1-3 (per section) | 30-45 min | +| Task 10: 7 new guides | 7-14 (per guide + index update) | 3-5 hours (textbook fidelity for new content) | +| Task 11: Verification | 1 (checkpoint) | 30-45 min | + +**Total estimated time:** 8-13 hours of focused single-agent work, spread across many per-file atomic commits. + +--- + +## Risks + +1. **Code evolution during the track:** Another agent is making code modifications. Each per-file rewrite starts with a `git add .` pre-edit checkpoint and reads the current source state. If a subsystem is restructured mid-track, the rewrite may need a follow-up commit. + +2. **Textbook / purple-tomb fidelity target:** This is ambitious. If we run out of time, we can ship a "good enough" pass on the main guides (3-6) and defer the new guides (10) to a follow-up track. + +3. **CLAUDE.md and AGENTS.md divergence:** This is Sub-Track 3 work, but if `AGENTS.md` and `docs/Readme.md` have conflicting pointer targets, the drift will be visible. Defer that conflict resolution to Sub-Track 3. + +--- + +**Gap analysis complete. Ready for Task 2.**