# 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.*