diff --git a/conductor/tracks/mma_implementation_20260224/synthesis.md b/conductor/tracks/mma_implementation_20260224/synthesis.md new file mode 100644 index 0000000..34fc8f3 --- /dev/null +++ b/conductor/tracks/mma_implementation_20260224/synthesis.md @@ -0,0 +1,28 @@ +# MMA Documentation Synthesis + +## Key Takeaways + +1. **Architecture Model**: 4-Tier Hierarchical Multi-Model Architecture mimicking a senior engineering department. + - **Tier 1 (Product Manager)**: High-reasoning models (Gemini 3.1 Pro/Claude 3.5 Sonnet) focusing on Epics and Tracks. + - **Tier 2 (Tech Lead)**: Mid-cost models (Gemini 3.0 Flash/2.5 Pro) for Track delegation, Ticket generation, and interface-driven development (Stub-and-Resolve). + - **Tier 3 (Contributors)**: Cheap/Fast models (DeepSeek V3/R1, Gemini 2.5 Flash) acting as amnesiac workers for heads-down coding. + - **Tier 4 (QA/Compiler)**: Ultra-cheap models (DeepSeek V3) for stateless translation of raw errors to human language. + +2. **Strict Context Management**: + - Uses `tree-sitter` for deterministic AST extraction (`Skeleton View`, `Curated Implementation View`, `Directory Map`). + - "Context Amnesia" ensures worker threads start fresh and do not accumulate hallucination-inducing token bloat. + +3. **Data Pipelines & Formats**: + - Tiers 1 & 2 output **Godot ECS Flat Relational Lists** (e.g., INI-style flat lists with `depends_on` pointers) to build DAGs. This avoids JSON nesting nightmares. + - Tier 3 uses **XML tags** (``, ``) to avoid string escaping friction. + +4. **Execution Flow**: + - The engine is decoupled from the UI using an `asyncio` event bus. + - A global **"Execution Clutch"** allows falling back from `async` parallel swarm mode to strict `linear` step mode for deterministic debugging and human-in-the-loop (HITL) overrides. + +## Constraints for Migration Plan + +- **Security**: `credentials.toml` must be strictly isolated and ignored in version control. +- **Phased Rollout**: Migration cannot be a single rewrite. It must follow strict tracks: AST Parser -> State Machine -> Linear Orchestrator -> Tier 4 QA -> UI Decoupling. +- **Tooling Constraints**: `tree-sitter` is mandatory for AST parsing. +- **UI State**: The GUI must be fully decoupled ("dumb" renderer) responding to queue events instead of blocking on LLM calls. \ No newline at end of file