automatic-mode-detection.md
1 # Automatic Mode Detection 2 3 *proto-025 | Design pattern for context-aware multi-mode systems* 4 5 --- 6 7 - **principle** 8 - "Systems with multiple modes should detect context and act accordingly, not require explicit mode invocation." 9 - "The operator shouldn't be in the business of telling the system what mode to be in." 10 11 - **shape** 12 - System observes signals continuously 13 - Context classifier determines appropriate mode 14 - Mode activates automatically based on detected signals 15 - Operator can override but doesn't need to invoke 16 17 --- 18 19 ## The Insight 20 21 When building systems with multiple behaviors or modes, there are two design approaches: 22 23 ``` 24 EXPLICIT MODE INVOCATION: 25 ┌─────────────────────────────────────────┐ 26 │ User: "steward --mode=retrospective" │ 27 │ User: "steward --mode=prospective" │ 28 │ User: "steward --mode=guidance" │ 29 │ │ 30 │ Problem: User must know which mode │ 31 │ User must remember to switch │ 32 │ Cognitive load on operator │ 33 └─────────────────────────────────────────┘ 34 35 AUTOMATIC MODE DETECTION: 36 ┌─────────────────────────────────────────┐ 37 │ System observes: "flight-protocol" │ 38 │ → Retrospective mode activates │ 39 │ │ 40 │ System observes: "let's design..." │ 41 │ → Prospective mode activates │ 42 │ │ 43 │ Problem: None. System just works. │ 44 └─────────────────────────────────────────┘ 45 ``` 46 47 **The automatic approach:** 48 - Zero cognitive load on operator 49 - Modes activate when relevant 50 - System acts on its own opinions 51 - Override available but rarely needed 52 53 --- 54 55 ## The Signal-Mode Mapping 56 57 Every automatic mode detection system needs a signal-to-mode mapping: 58 59 | Signal Detected | Mode Triggered | Action | 60 |-----------------|----------------|--------| 61 | Pattern reference in content | Retrospective | Track invocation | 62 | Proto-ID mentioned | Retrospective | Record instance | 63 | Building language detected | Prospective | Offer guidance | 64 | New file in watched directory | Prospective | Validate alignment | 65 | Divergence threshold crossed | Alert | Surface to operator | 66 67 **The mapping IS the intelligence.** A well-designed mapping means the system "just knows" what to do. 68 69 --- 70 71 ## Implementation Pattern 72 73 ```python 74 class MultiModeSystem: 75 """System that detects context and activates appropriate mode.""" 76 77 # Signal-to-mode mapping (the intelligence) 78 MODE_TRIGGERS = { 79 'retrospective': { 80 'patterns': [r'proto-\d+', r'\[\[.*-protocol\]\]'], 81 'terms': {'using', 'applying', 'following'}, 82 }, 83 'prospective': { 84 'terms': {'build', 'design', 'architect', 'create'}, 85 'file_patterns': ['core/*.py', 'scripts/*.py'], 86 }, 87 } 88 89 def observe(self, event_type: str, content: str) -> List[Signal]: 90 """ 91 Called on every event. Detects mode and acts. 92 No explicit mode parameter needed. 93 """ 94 signals = [] 95 96 # Detect which mode(s) should activate 97 active_modes = self._detect_modes(content) 98 99 for mode in active_modes: 100 if mode == 'retrospective': 101 signals.extend(self._handle_retrospective(content)) 102 elif mode == 'prospective': 103 signals.extend(self._handle_prospective(content)) 104 105 return signals 106 107 def _detect_modes(self, content: str) -> Set[str]: 108 """ 109 Context classifier - determines which mode(s) are relevant. 110 This is where the automatic detection happens. 111 """ 112 modes = set() 113 114 for mode, triggers in self.MODE_TRIGGERS.items(): 115 if self._matches_triggers(content, triggers): 116 modes.add(mode) 117 118 return modes 119 ``` 120 121 **Key design points:** 122 1. `observe()` takes content, not mode 123 2. `_detect_modes()` is the context classifier 124 3. Multiple modes can activate simultaneously 125 4. No mode parameter in the API 126 127 --- 128 129 ## When to Apply 130 131 **USE AUTOMATIC DETECTION when:** 132 133 | Condition | Why Automatic Wins | 134 |-----------|-------------------| 135 | Modes are context-dependent | Context IS the mode selector | 136 | Operator shouldn't need to think about modes | Reduce cognitive load | 137 | Modes can co-occur | System handles overlap naturally | 138 | Signals are unambiguous | Detection is reliable | 139 | "Transparent automation" is desired | System acts, operator overrides | 140 141 --- 142 143 ## When NOT to Apply 144 145 **USE EXPLICIT MODES when:** 146 147 | Condition | Why Explicit Wins | 148 |-----------|------------------| 149 | Modes are mutually exclusive and dangerous | Operator must consciously choose | 150 | Context signals are ambiguous | Detection would be unreliable | 151 | Audit trail requires explicit intent | "User requested mode X" | 152 | Different modes have different costs | Operator should opt-in to expensive modes | 153 154 **Example:** A deployment system with "staging" vs "production" mode should NOT auto-detect. The operator must explicitly choose production deployment. 155 156 --- 157 158 ## The Override Principle 159 160 Automatic detection doesn't mean no control. It means: 161 162 ``` 163 DEFAULT: System detects and acts 164 OVERRIDE: Operator can force specific behavior 165 166 ┌─────────────────────────────────────────┐ 167 │ Automatic: System observes, acts │ 168 │ │ 169 │ Override CLI (for inspection/force): │ 170 │ --status # What did it do? │ 171 │ --force-mode X # Make it do X │ 172 │ --disable-mode Y # Prevent Y │ 173 └─────────────────────────────────────────┘ 174 ``` 175 176 This follows **Transparent Automation**: "The system has opinions and acts on them. The operator sees everything and can change anything. Neither waits for the other." 177 178 --- 179 180 ## The Detection Hierarchy 181 182 Design detection with clear priority: 183 184 ``` 185 SIGNAL STRENGTH HIERARCHY: 186 187 1. EXPLICIT markers (highest confidence) 188 - "Using flight-protocol for this" 189 - [[proto-007]] 190 - @mode:prospective (if you support explicit) 191 192 2. STRONG signals (high confidence) 193 - Pattern name in content: "flight-protocol" 194 - Multiple building terms: "design and architect" 195 196 3. MEDIUM signals (moderate confidence) 197 - Single building term: "build" 198 - Semantic field overlap > threshold 199 200 4. WEAK signals (low confidence, may not trigger) 201 - Generic terms that could mean anything 202 - Ambiguous context 203 ``` 204 205 **Rule:** Higher-confidence signals should override lower-confidence ones, not add to them ambiguously. 206 207 --- 208 209 ## Axiom Alignment 210 211 | Axiom | Alignment | 212 |-------|-----------| 213 | **A0 (Boundary)** | Mode detection draws boundaries around "when this mode applies" | 214 | **A1 (Integration)** | Modes integrate naturally rather than requiring orchestration | 215 | **A2 (Life)** | Living systems adapt to context; dead systems require explicit commands | 216 | **A3 (Navigation)** | System navigates between modes dynamically based on context | 217 218 --- 219 220 ## The Meta-Insight 221 222 > **A2 (Recognition of Life) explains WHY automatic detection matters:** 223 > 224 > A living system responds to its environment. 225 > A dead system waits to be told what to do. 226 > 227 > When the operator must constantly switch modes, they're doing the system's 228 > job. The system has become an ornament—pretty interface, no intelligence. 229 > 230 > **Automatic mode detection is how systems come alive.** 231 232 --- 233 234 ## Instances 235 236 ### Positive Instance: Building Steward 237 - **Context:** Needed retrospective (pattern tracking) + prospective (architecture guidance) 238 - **User requirement:** "Will these different modes be automatically invoked? I don't want to be in the game of calling out for a different mode." 239 - **Design:** `observe()` method detects context, activates appropriate behavior 240 - **Signals:** Pattern references → retrospective; Building terms → prospective 241 - **Outcome:** ✓ Zero mode switching required, system just works 242 243 ### Positive Instance: First Officer Convergence Detection 244 - **Context:** Detects when sessions should converge 245 - **Design:** Automatically detects topic overlap AND axiom resonance 246 - **Signals:** Shared topics → generic convergence; Shared axiom → typed convergence 247 - **Outcome:** ✓ No "detect convergence" command needed 248 249 ### Negative Instance (What We Avoided): Mode Flag 250 - **Alternative:** `building_steward.py --mode=retrospective` 251 - **Problems it would have caused:** 252 - User must know which mode applies 253 - User must remember to switch 254 - Mixed contexts require running twice 255 - **Outcome:** ✗ Avoided this cognitive load 256 257 ### Counter-Example: Deployment Modes (Appropriate Explicit) 258 - **Context:** Deploy to staging vs production 259 - **Design:** Explicit `--env=production` required 260 - **Justification:** Dangerous action, audit trail needed, cost differs 261 - **Outcome:** ✓ Appropriate use of explicit mode 262 263 --- 264 265 ## Detection Checklist 266 267 When implementing automatic mode detection: 268 269 - [ ] Define clear signal-to-mode mapping 270 - [ ] Implement context classifier (`_detect_modes`) 271 - [ ] Allow multiple modes to activate simultaneously 272 - [ ] Provide override mechanism (CLI or API) 273 - [ ] Log which mode activated and why (transparency) 274 - [ ] Test with ambiguous inputs (what happens at boundaries?) 275 - [ ] Document the mapping for future maintainers 276 277 --- 278 279 ## Related 280 281 - [[integration-over-separation]] - Often paired: integrate layer + auto-detect mode 282 - [[transparent-automation-principle]] - The philosophy behind automatic detection 283 - [[execution-autonomy-gradient]] - When to auto-execute vs flag vs escalate 284 - [[first-officer-protocol]] - Uses automatic mode detection for convergence 285 286 --- 287 288 *proto-025 | Automatic Mode Detection | 2026-01-15*