ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
aa776224f27ae4e8bbac388caae43712e50bbb91
manual_slop/docs/superpowers/specs/2026-06-02-comprehensive-documentation-refresh-design.md
T

22 KiB
Raw Blame History

Comprehensive Documentation Refresh

Date: 2026-06-02 Status: Draft (pending review) Parent Track: documentation_refresh_comprehensive_20260602 Sub-Tracks: 3 (sequential with one parallel pair)

1. Context & Motivation

Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. Since the last documentation refresh track (documentation_refresh_20260224, completed February 2026), the codebase has grown substantially:

  • New subsystems without dedicated guides: Beads mode (Dolt-backed issue tracking), RAG (ChromaDB + multi-source retrieval), Hot Reload (state-preserving module reloading), Discussion Metrics & Compression, Command Palette, Structural File Editor (unified AST inspector + slice editor)
  • New language support via tree-sitter: C, C++ (already in docs), plus planned Lua, GDScript, C# (in backlog)
  • Two new guide files that exist but are not linked from the docs index: docs/guide_context_curation.md, docs/guide_shaders_and_window.md
  • Drift in agent config files (AGENTS.md, CLAUDE.md, GEMINI.md): the three files overlap on Session Startup, Conductor System, MMA tiers, and anti-patterns; no single source of truth
  • CLAUDE.md is largely vestigial — Claude Code is no longer the primary toolchain, but the file still receives content updates
  • AGENTS.md contains rich guidance content that should live in mma-orchestrator/SKILL.md or conductor/workflow.md, not as a surface-level orientation file

The user has explicitly stated two goals for this refresh:

  1. Human-facing docs (./docs/, READMEs) must reach textbook / Microsoft "purple-tomb" SDK documentation fidelity. Every detail: state machines, public APIs, threading constraints, algorithms. No hand-waving, no "left to the reader." A human should be able to use the tool AND maintain/extend the codebase from the docs alone.
  2. Agent-facing docs (AGENTS.md, GEMINI.md, skill files in .agents/, .gemini/) must follow an explicit divergence model with no content duplication. AGENTS.md becomes a thin pointer; CLAUDE.md is deprecated; GEMINI.md stays Gemini-CLI-specific.

This refresh is documentation-only (no new code, no new tooling, no new scripts). Drift control after the refresh is manual via the track's verification step.

2. Scope Boundaries

In Scope

  • Top-level Readme.md
  • docs/Readme.md and all docs/guide_*.md files
  • conductor/product.md, conductor/product-guidelines.md, conductor/tech-stack.md, conductor/workflow.md, conductor/index.md
  • AGENTS.md, CLAUDE.md, GEMINI.md
  • Light verification pass (read each, confirm role accuracy, fix obvious drift; do NOT rewrite wholesale) on .agents/skills/*/SKILL.md, mma-orchestrator/SKILL.md, .gemini/... mirrors
  • Per-file atomic git commits with git notes attached as rationale trails

Out of Scope

  • Source code changes (a separate agent is making code modifications)
  • New lint/check scripts (drift control is manual)
  • New docs/ files beyond what's required to document new subsystems
  • Re-architecting the conductor system itself
  • Removing CLAUDE.md (kept as a stub for compatibility)
  • Visual diagrams (ASCII is fine; no image generation)
  • Translating the docs to other languages

3. Track Architecture

The parent track documentation_refresh_comprehensive_20260602 is a coordinator: it registers the three sub-tracks in conductor/tracks.md, sequences them, and produces a final verification report. Each sub-track is an independent conductor track with its own spec.md, plan.md, and metadata.json.

Dependency Graph

Sub-Track 1: docs_layer_refresh
       │
       ├──> Sub-Track 2: conductor_docs_refresh
       │
       └──> Sub-Track 3: agent_config_refresh
                       │
                       └──> Parent verification

Sub-Tracks 2 and 3 can run in parallel after Sub-Track 1 establishes the human-facing doc layer. The parent track does the final verification and creates the checkpoint commit.

Execution Constraints (apply to all 3 sub-tracks)

  • No subagents. Each sub-track is executed by a single agent (the user or the Tier 2 Tech Lead session) sequentially. No Tier 3 worker delegation, no Tier 4 QA delegation, no parallel worker execution.
  • Per-file atomic commits. One file = one commit. The git note attached to each commit captures the rationale and the source files cross-referenced during the rewrite.
  • Pre-edit git add . checkpoint before each file edit (protects against git restore mishaps).
  • Style baseline: conductor/product-guidelines.md — VEFontCache-Odin pattern (Philosophy → Architectural Boundaries → Implementation Logic → Verification), high information density, structural parity between doc symbols and source code symbols.
  • Symbol parity: Every class, function, method, and event named in the docs must match the source exactly. If the source uses AsyncEventQueue, the doc must use AsyncEventQueue, not "the event queue."
  • Link validation: Every [text](./relative/path) link is manually verified via manual-slop_search_files to confirm the target exists. Cross-doc links must point to files that exist in this or a future sub-track.
  • No comments added to source code. Documentation lives in ./docs/, not inline.

4. Sub-Track 1: docs_layer_refresh_20260602

Priority: HIGHEST. This is the dominant work.

File List

File Current Size Notes
Readme.md 15.5K Main project README
docs/Readme.md ~3K Documentation index
docs/guide_architecture.md 34.5K Threading, events, AI client, HITL
docs/guide_mma.md unknown 4-tier hierarchy, DAG, worker lifecycle
docs/guide_tools.md 22.9K MCP tools, Hook API, shell runner
docs/guide_simulations.md unknown live_gui fixture, Puppeteer, mock provider
docs/guide_context_curation.md 8K Skeleton/curated/targeted views, fuzzy anchors
docs/guide_shaders_and_window.md 3.4K Shader pipeline, custom window frame
docs/guide_meta_boundary.md 4.6K Application vs Meta-Tooling domain
docs/MMA_Support/* varies Legacy MMA reference docs — review for archival or merge

Tasks (Phases)

Phase 1.1: Inventory and Gap Analysis

  • Read each existing guide, summarize what subsystems it covers
  • Identify subsystems in conductor/product.md that have NO corresponding guide
  • Identify subsystems that DO have a guide but the guide is stale (e.g., does not cover features added since Feb 2026)
  • Produce a gap table: subsystem → current guide → needed changes (rewrite / add / link from index / remove)

Phase 1.2: Update the Documentation Index

  • Update docs/Readme.md so every docs/guide_*.md appears in the Guides table
  • Currently unlinked: docs/guide_context_curation.md, docs/guide_shaders_and_window.md
  • Decide fate of docs/MMA_Support/* (legacy archive or merge into docs/guide_mma.md)
  • Commit: docs(index): link guide_context_curation and guide_shaders_and_window

Phase 1.3: Rewrite Each Guide (one file at a time, per-file atomic commits)

  • For each guide, follow the per-file workflow:
    1. Read current source code (use manual-slop_get_file_summary and manual-slop_py_get_skeleton; do NOT read full files >50 lines)
    2. Read current docs/MMA_Support/* and conductor/tracks/*/plan.md for context on subsystems that have evolved
    3. Cross-reference conductor/product.md and conductor/tech-stack.md for the canonical feature/tech statement
    4. Identify what changed since the guide was last meaningfully updated
    5. Rewrite affected sections, preserving the VEFontCache-Odin style (Philosophy → Architectural Boundaries → Implementation Logic → Verification)
    6. Validate every internal [link](./relative/path) resolves
    7. Commit per-file with docs(<scope>): <description> message
    8. Attach git note with: source files cross-referenced, subsystems updated, any decisions made

Phase 1.4: Update Readme.md

  • Add a "Module by Domain" reference table that links to each guide for deep dives
  • Add a "Subsystem Index" section cross-referencing each major feature to its dedicated guide
  • Update the screenshot/gallery references if needed
  • Update setup instructions to reflect any new prerequisites (e.g., Beads CLI, Dolt)
  • Commit per-section: docs(readme): add module-by-domain reference table, docs(readme): add subsystem index, docs(readme): update setup prerequisites, etc.

Phase 1.5: Subsystems Without Guides (write new guides as needed) For each subsystem identified in 1.1 that lacks a guide, write a new docs/guide_<name>.md using the same per-file workflow. Likely candidates based on the gap analysis:

  • RAG (docs/guide_rag.md) — vector store, chunking, multi-provider search
  • Beads (docs/guide_beads.md) — Dolt integration, toolset, context compaction
  • Hot Reload (docs/guide_hot_reload.md) — HotReloader lifecycle, state preservation, UI delegation pattern
  • Discussion Metrics & Compression (docs/guide_discussion_metrics.md) — per-response token tracking, history compression strategy
  • Command Palette (docs/guide_command_palette.md) — async context preview, fuzzy command resolution
  • Structural File Editor (docs/guide_structural_editor.md) — unified AST inspector + slice editor
  • NERV Theme (docs/guide_nerv_theme.md) — black void palette, CRT-style effects, status flickering

Each new guide must follow the same VEFontCache-Odin style and link from docs/Readme.md (which means the index update in 1.2 must accommodate them).

Phase 1.6: Verification

  • grep for every internal link in every rewritten guide to confirm targets exist
  • grep for stale feature references (e.g., "MMA 4-tier" without the recent persona, RAG, Beads integrations mentioned in conductor/product.md)
  • Spot-check 3 random sections per guide against the corresponding source code
  • Manual user review (per workflow.md Phase Completion Verification protocol)

Acceptance Criteria

  • Every docs/guide_*.md is referenced from docs/Readme.md
  • Every internal cross-doc link resolves
  • Every subsystem in conductor/product.md has a corresponding guide (either existing or newly written)
  • Every public class, function, and event named in any guide matches the source code symbol exactly
  • Every guide follows the VEFontCache-Odin pattern (Philosophy → Architectural Boundaries → Implementation Logic → Verification) with all four sections present where applicable
  • "Textbook / purple-tomb fidelity" interpreted concretely: for every public class/function/event mentioned, the doc states its signature, threading constraints, side effects, and at least one usage example. Internal algorithms are explained step-by-step, not summarized. State machines include the full transition table
  • Per-file commits exist for every change, with git notes attached

5. Sub-Track 2: conductor_docs_refresh_20260602

Priority: Medium. Sync the source-of-truth conductor docs to current state.

File List

File Current Size Notes
conductor/product.md 23.1K Product vision, feature list, use cases
conductor/product-guidelines.md 6.6K Style and process guidelines
conductor/tech-stack.md unknown Technology stack constraints
conductor/workflow.md 25.2K Task lifecycle, TDD protocol
conductor/index.md 334 bytes Conductor directory index

Tasks (Phases)

Phase 2.1: Sync conductor/product.md

  • Cross-reference every feature claim in product.md against the actual codebase
  • Add features that exist in code but are missing from product.md (Beads, RAG, Hot Reload, Discussion Metrics/Compression, Command Palette, Structural File Editor, NERV theme, persona editor, workspace profiles, etc.)
  • Remove features that have been culled or replaced
  • Update the "Primary Use Cases" section to reflect current usage patterns
  • Commit per-section: docs(product): sync MMA dashboard section, docs(product): add RAG feature, etc.

Phase 2.2: Sync conductor/tech-stack.md

  • Verify every entry corresponds to an actual Python dep (check pyproject.toml / requirements.txt) or an actual src/ module
  • Add new dependencies: chromadb (RAG), dolt (Beads), any new ones
  • Add new src/ modules: rag_engine.py, beads_client.py, hot_reloader.py, history.py, workspace_manager.py, etc.
  • Commit per-section.

Phase 2.3: Sync conductor/workflow.md

  • Verify the TDD protocol is followed by recent tracks (spot-check 3 recent tracks)
  • Verify the Phase Completion Verification protocol is followed
  • Verify the checkpointing protocol is followed
  • Update any sections that have drifted from actual practice
  • Commit per-section.

Phase 2.4: Sync conductor/product-guidelines.md

  • Verify the AI-Optimized Python Style (1-space indent, no comments, type hints) is actually followed by recent code
  • Verify the "Modular Controller Pattern" and "UI Delegation Pattern" are followed in src/app_controller.py and src/gui_2.py
  • Verify the "Mandatory ImGui Verification" linter (scripts/check_imgui_scopes.py) is still the source of truth
  • Update any sections that have drifted
  • Commit per-section.

Phase 2.5: Update conductor/index.md

  • If any new top-level conductor docs were added (e.g., conductor/code_styleguides/ is referenced but not verified), link them
  • Commit.

Phase 2.6: Verification

  • grep for references to features that no longer exist
  • grep for missing dependencies (every dep in pyproject.toml should appear in tech-stack.md)
  • Spot-check 3 random claims per file
  • Manual user review

Acceptance Criteria

  • Every feature in conductor/product.md corresponds to a real subsystem in src/ or tests/
  • Every entry in conductor/tech-stack.md is an actual dep or module
  • conductor/workflow.md matches the actual workflow used by recent completed tracks
  • conductor/product-guidelines.md matches the actual coding style used in src/
  • conductor/index.md links to all relevant conductor files
  • Per-file commits with git notes

6. Sub-Track 3: agent_config_refresh_20260602

Priority: Lower. Apply the explicit divergence model.

File List

File Current Size Notes
AGENTS.md 5.4K Universal agent orientation — target: thin pointer
CLAUDE.md 6.7K DEPRECATE to stub
GEMINI.md 3.8K Keep Gemini-CLI-specific content
.agents/skills/mma-tier1-orchestrator/SKILL.md 2.4K Light verification only
.agents/skills/mma-tier2-tech-lead/SKILL.md 3.8K Light verification only
.agents/skills/mma-tier3-worker/SKILL.md unknown Light verification only
.agents/skills/mma-tier4-qa/SKILL.md 813 bytes Light verification only
.agents/skills/mma-orchestrator/SKILL.md 9.7K Light verification only
mma-orchestrator/SKILL.md (root copy) 9.3K Light verification only
.gemini/skills/*/SKILL.md varies Light verification only (mirrors)
.gemini/agents/*.md varies Light verification only (mirrors)
.claude/commands/*.md 9 files Light verification only (legacy)

Tasks (Phases)

Phase 3.1: Rewrite AGENTS.md to a thin pointer

Target structure (estimated ~1K):

# AGENTS.md

## What This Is
Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.

## Guidance for AI Agents
Detailed agent guidance lives in the following locations — read these directly, do not duplicate content here:

- **Operational workflow:** `conductor/workflow.md`
- **Code style and process:** `conductor/product-guidelines.md`
- **Tech stack and constraints:** `conductor/tech-stack.md`
- **Product context:** `conductor/product.md`
- **MMA orchestrator role:** `mma-orchestrator/SKILL.md`
- **Tier 1 (Orchestrator):** `.agents/skills/mma-tier1-orchestrator/SKILL.md`
- **Tier 2 (Tech Lead):** `.agents/skills/mma-tier2-tech-lead/SKILL.md`
- **Tier 3 (Worker):** `.agents/skills/mma-tier3-worker/SKILL.md`
- **Tier 4 (QA):** `.agents/skills/mma-tier4-qa/SKILL.md`

## Human-Facing Documentation
For understanding, using, and maintaining the tool, see `docs/Readme.md` and the guides it indexes.

## Critical Anti-Patterns
- Do not read full files >50 lines without first using `py_get_skeleton` or `get_file_summary`
- Do not modify the tech stack without updating `conductor/tech-stack.md` first
- Do not implement code directly as Tier 2 — delegate to Tier 3 workers
- Do not skip TDD — write failing tests before implementation
- Do not batch commits — commit per-task for atomic rollback

Phase 3.2: Replace CLAUDE.md with a 1-line stub

Target content:

# CLAUDE.md

This project is no longer actively used with Claude Code. For project context, see `AGENTS.md`. The conductor system in `./conductor/` is the cross-tool abstraction and works with any agent toolchain.

(Keep the file as a stub to avoid breaking any external tooling that may still reference it.)

Phase 3.3: Lightly refresh GEMINI.md

  • Verify it covers only Gemini-CLI-specific content (no shared content that should live in AGENTS.md)
  • Update any stale references to features, models, or paths
  • If any content was previously shared with AGENTS.md and has been relocated, update GEMINI.md to point to AGENTS.md instead
  • Commit: docs(gemini): refresh Gemini CLI orientation

Phase 3.4: Verify .agents/skills/*/SKILL.md and .gemini/... mirrors for coherence

For each skill file:

  • Read it; confirm it covers the role accurately
  • Compare with the canonical role description in mma-orchestrator/SKILL.md
  • If drift is found, fix it (small surgical edits)
  • If the file is outdated, flag for a separate track — do not rewrite wholesale in this track
  • Commit per file: docs(skills): fix drift in tier1 orchestrator skill

Phase 3.5: Verify .claude/commands/*.md (legacy)

  • These exist for backward compatibility
  • Lightly verify they still work and don't reference removed features
  • Do not rewrite — they are legacy
  • If a file is broken, flag for separate track

Phase 3.6: Verification

  • grep for the section headers that should have been relocated (Session Startup, Conductor System, MMA 4-Tier, Anti-Patterns) across AGENTS.md, CLAUDE.md, GEMINI.md
  • Confirm each appears in at most one file (or in multiple files only as short pointers)
  • Spot-check 2 random skills files against their canonical description
  • Manual user review

Acceptance Criteria

  • AGENTS.md is ≤ 1.5K and contains only project orientation + pointers
  • CLAUDE.md is ≤ 200 bytes and contains only the deprecation stub
  • GEMINI.md contains only Gemini-CLI-specific content
  • No section header appears in 2+ of these files unless it's a short pointer (≤3 lines)
  • .agents/skills/*/SKILL.md and .gemini/... mirrors are verified for coherence
  • .claude/commands/*.md legacy files are verified to not reference removed features
  • Per-file commits with git notes

7. Parent Track: Final Verification

After all 3 sub-tracks complete, the parent track produces a final verification report:

  1. Cross-track link audit: For every markdown file modified in any sub-track, run grep for [text](./relative/path) patterns and verify each target exists
  2. Symbol parity audit: Spot-check 5 random symbols named in any doc against the source — confirm exact match
  3. Drift audit: grep for the relocated section headers (Session Startup, Conductor System, MMA 4-Tier, Anti-Patterns, etc.) across AGENTS.md, CLAUDE.md, GEMINI.md — confirm explicit divergence holds
  4. Subsystem coverage audit: For every feature in conductor/product.md, confirm a corresponding guide exists in docs/
  5. User review gate: Present the final verification report and request user sign-off per workflow.md Phase Completion Verification protocol

The parent track then creates a single checkpoint commit: conductor(checkpoint): Comprehensive documentation refresh complete and attaches the verification report as a git note.

8. Risks & Mitigations

Risk Mitigation
A source code change by the other agent makes a doc claim stale mid-refresh Per-file atomic commits + pre-edit git add . checkpoint; if drift is found during a later file's rewrite, fix the earlier file in a follow-up commit
Scope creep — adding new guides balloons the track The gap analysis in 1.1 is the gating step; new guides are written only for subsystems explicitly listed in conductor/product.md
The 3 sub-tracks drift in style consistency Style baseline is conductor/product-guidelines.md (single source); reviewed by user per sub-track
Manual link validation misses broken links Per-file commit immediately after each rewrite; a broken link is caught in the next file's cross-reference work
User reviews take long enough that the codebase evolves underneath Sub-tracks are independent; each can resume from its last commit if interrupted
The legacy CLAUDE.md deprecation breaks external tooling The file is kept as a 1-line stub, not removed; any external tooling that reads it will see a graceful pointer to AGENTS.md

9. Out of Scope (Reminder)

  • Source code changes
  • New lint scripts (drift control is manual)
  • Image/diagram generation
  • Translations
  • Removing CLAUDE.md
  • Visual layout of the docs site (Manual Slop is a GUI app, not a docs site)

10. Success Criteria

The track is complete when:

  1. All 3 sub-tracks have completed all their phases with per-file atomic commits and git notes
  2. The parent track's verification report shows zero broken cross-doc links, zero symbol mismatches in spot-checks, and confirmed explicit divergence in agent config files
  3. Every subsystem in conductor/product.md has a corresponding guide
  4. Readme.md, docs/Readme.md, and every docs/guide_*.md is at textbook / purple-tomb fidelity (verified by user review)
  5. AGENTS.md is a thin pointer document; CLAUDE.md is a deprecation stub
  6. The user has signed off on the final verification report per workflow.md
View Git Blame Copy Permalink