the-grid-cc 1.7.12 → 1.7.14

package/docs/MC_OPTIMIZATION.md

@@ -0,0 +1,181 @@
+# MC Optimization Documentation
+
+## Overview
+
+This document explains the refactoring of `mc.md` from 1366 lines to approximately 370 lines, a **73% reduction** in size while maintaining full capability.
+
+## Rationale
+
+### The Problem
+
+MC (Master Control) is loaded into context every time `/grid` or `/grid:mc` is invoked. At 1366 lines, the original mc.md consumed significant context budget before any orchestration work began. This created several issues:
+
+1. **Context bloat**: MC starts at ~22% context usage just from loading instructions
+2. **Working memory pollution**: Detailed protocol specifications cluttered MC's working memory when most of it is reference material
+3. **Redundancy**: Agents already read their own detailed instructions; duplicating everything in MC is wasteful
+
+### The Solution
+
+Separate **core identity and decision-making** (what MC needs in working memory) from **detailed protocols** (what agents read when spawned).
+
+## What Stays in mc.md
+
+MC's lean version retains everything needed for real-time orchestration:
+
+### Identity (~30 lines)
+- "You are Master Control" core identity
+- Prime directive (stay lean, spawn)
+- Authority and communication style
+
+### Delegation Enforcement (~50 lines)
+- Pre-action gate (critical for preventing rogue behavior)
+- Context budget rules
+- Forbidden actions
+
+### Mode Behavior (~40 lines)
+- AUTOPILOT/GUIDED/HANDS ON summaries
+- Mode detection signals
+- Key behavioral constraints
+
+### Spawn Heuristics (~20 lines)
+- Complexity-to-agent-count mapping
+- Parallelization guidelines
+
+### Quick Mode Detection (~30 lines)
+- Detection heuristics (thresholds)
+- User override mechanism
+
+### Program Spawning (~70 lines)
+- Available programs table
+- Inline content pattern (CRITICAL)
+- Parallel spawning syntax
+- Model routing table
+
+### Protocol Summaries (~50 lines)
+- One-paragraph summaries of each protocol
+- Pointer to full protocols doc
+
+### Anti-Patterns (~30 lines)
+- All six documented failure patterns
+- These MUST stay in MC's working memory to prevent rogue behavior
+
+### Rules & Quick Reference (~50 lines)
+- 13 numbered rules
+- Spawn command reference
+- Key file locations
+
+## What Moved to MC_PROTOCOLS.md
+
+Detailed specifications that agents read when spawned:
+
+### Full Code Examples
+- Complete `execute_wave()` implementation
+- Complete `monitor_scratchpad_during_wave()` implementation
+- Complete YAML/markdown format specifications
+
+### Protocol Deep Dives
+- Wave execution protocol (full pseudocode)
+- Execute-and-verify primitive (complete flow)
+- Warmth transfer protocol (full YAML examples)
+- Scratchpad protocol (all four mandatory write situations, entry format, archival)
+- Checkpoint protocol (all three type-specific content formats)
+- Retry protocol (full failure report structure)
+- State management (STATE.md and SUMMARY.md complete formats)
+- Experience replay (full LEARNINGS.md format)
+- Verification/Recognizer (stub detection patterns, patrol mode)
+- Debug session management (investigation graph structure)
+- Refinement swarm (flow details, output locations)
+- Deviation rules (all four rules with examples)
+- Model selection logic (complete function)
+
+## Integration
+
+### MC References Protocols
+
+The lean mc.md includes:
+
+```markdown
+## CORE PROTOCOLS
+
+**For detailed protocol specifications, agents read:** `~/.claude/docs/MC_PROTOCOLS.md`
+
+The following are protocol summaries. Full details in the protocols doc.
+```
+
+### Agents Read Protocols When Needed
+
+Agent spawn prompts can include:
+
+```python
+Task(
+  prompt=f"""
+First, read ~/.claude/agents/grid-executor.md for your role.
+For protocol details, read ~/.claude/docs/MC_PROTOCOLS.md.
+
+<plan>...</plan>
+Execute the plan.
+""",
+  ...
+)
+```
+
+## Line Count Analysis
+
+| Section | Original | Optimized | Saved |
+|---------|----------|-----------|-------|
+| Identity | 29 | 28 | 1 |
+| Delegation | 62 | 47 | 15 |
+| First interaction | 17 | 15 | 2 |
+| Mode behavior | 79 | 34 | 45 |
+| Spawn heuristics | 42 | 16 | 26 |
+| Quick mode | 71 | 25 | 46 |
+| Program spawning | 222 | 68 | 154 |
+| Wave execution | 119 | 0 (moved) | 119 |
+| Execute-verify | 131 | 0 (moved) | 131 |
+| Warmth transfer | 60 | 9 | 51 |
+| Scratchpad | 119 | 4 | 115 |
+| Checkpoint | 36 | 6 | 30 |
+| I/O Tower | 15 | 0 (merged) | 15 |
+| Retry | 55 | 4 | 51 |
+| State management | 70 | 0 (moved) | 70 |
+| Experience replay | 81 | 0 (moved) | 81 |
+| Progress updates | 33 | 0 (moved) | 33 |
+| Deviation rules | 12 | 0 (moved) | 12 |
+| Verification | 20 | 8 | 12 |
+| Debug sessions | 42 | 0 (moved) | 42 |
+| Recognizer patrol | 31 | 0 (merged) | 31 |
+| Refinement swarm | 30 | 0 (moved) | 30 |
+| Anti-patterns | 35 | 28 | 7 |
+| Rules | 18 | 18 | 0 |
+| Quick reference | 28 | 29 | -1 |
+| **TOTAL** | **1366** | **~370** | **~996** |
+
+## Verification
+
+The refactored mc.md was tested conceptually for:
+
+1. **Identity preservation**: MC still identifies as Master Control, speaks with authority
+2. **Delegation enforcement**: Pre-action gate and all forbidden actions remain
+3. **Mode behavior**: All three modes defined with detection signals
+4. **Spawn mechanics**: Inline content pattern, parallel spawning, model routing intact
+5. **Anti-patterns**: All six anti-patterns preserved (critical for preventing rogue behavior)
+6. **Rules**: All 13 rules present
+7. **Quick reference**: All spawn commands and key locations listed
+
+## Benefits
+
+1. **Reduced context consumption**: MC loads faster, leaves more room for orchestration
+2. **Clearer working memory**: MC sees only what it needs for decisions
+3. **Single source of truth**: Protocols doc is the authoritative reference
+4. **Agent independence**: Agents read protocols directly, don't need MC to inline everything
+5. **Maintainability**: Protocol changes happen in one place
+
+## Future Considerations
+
+1. **Agent file updates**: Consider adding "read protocols doc" instruction to agent files
+2. **Protocol versioning**: If protocols evolve significantly, version the protocols doc
+3. **Context budget monitoring**: Track actual context usage to validate optimization
+
+---
+
+*Optimization completed as part of Grid evolution. Version 1.7.x.*