connectonion 0.6.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

connectonion/docs/design-decisions/015-interactive-auto-debug-design.md

@@ -0,0 +1,837 @@
+# Design Decision: Interactive Auto-Debug - The Journey to Simplicity
+
+*Date: 2025-10-05 (Updated: 2025-10-06)*
+*Status: Implemented in v0.1.8*
+*Decision: Agent-first menu-based REPL with progressive disclosure*
+
+## The Problem: AI Agents Are Black Boxes
+
+AI agents make decisions we can't see. They call tools, process results, and continue - all invisible to developers. When something goes wrong, we're stuck with:
+
+```python
+agent = Agent("assistant", tools=[search, calculate])
+agent.input("Find the answer")
+# *mysterious processing happens*
+# Something broke... but where? why? how?
+```
+
+**Debugging AI agents felt like debugging in the dark.**
+
+## First Attempt: Traditional CLI Tools
+
+Our initial instinct was familiar territory - CLI debugging commands:
+
+```bash
+# Traditional approach
+co debug agent.py          # Enter debug mode
+co step                    # Step through tools
+co inspect                 # View state
+co retry --modify          # Retry with changes
+```
+
+**Why this felt right:**
+- Developers know CLI tools (gdb, pdb, lldb)
+- Separate commands = clear separation of concerns
+- Easy to document each command
+
+**But something felt wrong.**
+
+## The User's Insight: "CLI Needs Learning, auto_debug Is Intuitive"
+
+During design review, the critical feedback came:
+
+> "I think CLI needs users to learn, but `agent.auto_debug()` is intuitive..."
+
+This stopped us cold. **They were absolutely right.**
+
+The CLI approach:
+- ✗ Requires learning new commands (`co debug`, `co step`, `co inspect`)
+- ✗ Breaks the Python development flow
+- ✗ Adds cognitive overhead (remember command syntax)
+- ✗ Feels separate from the code
+
+But `agent.auto_debug()`:
+- ✓ Discovered through autocomplete
+- ✓ Natural Python method call
+- ✓ Works in any environment (REPL, notebook, script)
+- ✓ Feels like part of the agent
+
+**The insight: The best interface is one you don't have to learn.**
+
+## Rethinking: The User Journey First
+
+We paused implementation and asked a different question:
+
+**"What does a developer WANT when debugging an AI agent?"**
+
+Not what features we can build. What problems they're trying to solve.
+
+### The First-Time User Journey
+
+```python
+# User writes agent
+agent = Agent("assistant", tools=[search])
+
+# Something breaks or they're curious
+agent.input("Find the answer")  # Tool calls happen... confused
+
+# They discover auto_debug (via docs, autocomplete, or trial)
+agent.auto_debug()
+agent.input("Find the answer")
+
+# [INTERACTIVE MENU APPEARS]
+# ┌─────────────────────────────────────┐
+# │  🔧 Agent paused at: search         │
+# │  Arguments: {'query': 'answer'}     │
+# │                                     │
+# │  ❯ Continue                         │
+# │    AI Help - Ask questions          │
+# │    Python Edit - Modify variables   │
+# │    View Trace - See execution       │
+# │                                     │
+# │  💡 Use ↑↓ arrows • Enter to select │
+# └─────────────────────────────────────┘
+```
+
+**This felt right.** No commands to remember. No syntax to learn. Just navigate and select.
+
+## The Design Evolution: Four Iterations to Simplicity
+
+But getting to this final design required four complete iterations, each teaching us something critical about simplicity and user experience.
+
+### Iteration 1: The Complex Four-Mode Design (REJECTED)
+
+Our first instinct after rejecting CLI was to build a comprehensive debugging system with four distinct modes:
+
+```
+🔍 Debug Mode Active
+
+Modes:
+- CHAT: Talk to agent normally
+- EDIT: Modify execution state
+- SIM: Simulate different scenarios
+- VIEW: Inspect execution trace
+
+Current: CHAT mode
+agent>
+```
+
+**User feedback:** *"I think 4 is too complicated, two or three at most"*
+
+**Why it failed:**
+- Too many modes to understand upfront
+- Unclear when to use which mode
+- High learning curve before being productive
+- Violated "keep simple things simple" principle
+
+**Key lesson:** More features ≠ better UX. Start with less.
+
+### Iteration 2: Prefix-Based Mode Switching (REJECTED)
+
+We tried simplifying with prefix characters to indicate different targets:
+
+```
+agent> Hello                    # Send to agent (default)
+agent> ? why did it fail        # Ask AI debugger for help
+agent> >>> result = []          # Python code execution mode
+```
+
+**User feedback:** *"when we do auto-debug, sometimes we input something. Sometimes we want to input what we want to input to the agent. The input of the agent should default have a mode"*
+
+**Why it failed:**
+- Prefix characters (`?`, `>>>`) not immediately discoverable
+- Don't clearly communicate purpose without documentation
+- Still confusing about who receives the input
+- Default mode wasn't obvious enough
+
+**Key lesson:** Symbolic shortcuts require learning. Need explicit mode indicators.
+
+### Iteration 3: Mode Indicators with Prompts (BETTER)
+
+We added clear, named mode indicators:
+
+```
+agent> Send email to John       # To agent (default)
+
+ai> why did it send wrong email # To AI debugger for help
+
+>>> result = "correct@email"    # Python execution mode
+```
+
+**User feedback:** *"The AI should be something more intuitive like AI Ask or something like that"*
+
+**Progress made:**
+- Clear visual mode indicators (`agent>`, `ai>`, `>>>`)
+- Default to agent input (matches user mental model)
+- Separate AI help and Python modes
+
+**Still needed work:**
+- Mode names not intuitive enough (`ai>` → what does "ai" mean here?)
+- Switching between modes unclear (how do I get back?)
+- Missing visual guidance for mode transitions
+- `/inspect` vs `/code` distinction unclear
+
+**Key lesson:** Names matter. "AI" is ambiguous - "AI Ask" is self-explanatory.
+
+### Iteration 4: Agent-First Menu with Universal Commands (FINAL) ✅
+
+The breakthrough came from asking: **"What would Unix creators or Steve Jobs design?"**
+
+This question forced us to apply fundamental design principles:
+
+**Unix Philosophy Applied (Ken Thompson, Dennis Ritchie):**
+- **Do one thing well** - Each mode has single, clear purpose
+- **Composition over complexity** - Combine simple parts, don't create complex wholes
+- **No unnecessary features** - Eliminate what isn't essential
+- **Text streams** - Input/output flows naturally
+
+**Steve Jobs Influence (Apple Design):**
+- **Eliminate the unnecessary** - Remove mode switching complexity entirely
+- **Focus on the essence** - What does user REALLY need? Continue execution.
+- **Intuitive over learnable** - No manual required, just use it
+- **Design is how it works** - Menu isn't decoration, it IS the interface
+
+**Final Design:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+@xray BREAKPOINT: search_emails
+
+Local Variables:
+  query = "John"
+  result = "Found 1 email from john@company.com"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What do you want to do?
+  → Continue execution       [Enter or c]
+    Ask AI for help          [a]
+    Edit variables (Python)  [e]
+    View execution trace     [v]
+    Toggle step mode        [s]
+    Stop debugging          [q]
+
+💡 Use ↑↓ arrows and Enter, or type shortcuts
+>
+```
+
+**Why this works:**
+
+1. **Agent-first by default** - Just press Enter to continue (simplest action)
+2. **Progressive disclosure** - See all options, discover gradually (no hidden features)
+3. **Consistent patterns** - All commands use `/` when in modes (`/menu`, `/continue`)
+4. **Multiple input methods** - Arrow keys (beginner-friendly) OR shortcuts (power users)
+5. **Always visible help** - Tips show how to use it, zero memorization
+6. **No dead ends** - `/menu` and `/continue` work everywhere (universal escape hatches)
+
+**Key lesson:** The best design makes the default action effortless and everything else discoverable.
+
+## The Design Shift: Menu-Based Interactive UX
+
+### Core Principle: Arrow Keys > Typed Commands
+
+Instead of:
+```
+(debug) help
+(debug) inspect query
+(debug) retry --modify query="better search"
+```
+
+We designed:
+```
+[Use ↑↓ arrows to navigate, Enter to select]
+
+❯ Continue
+  AI Help - Ask me anything
+  Python Edit - Modify execution state
+  View Trace - See full history
+  Step Mode - Pause at every tool
+```
+
+**Why arrow keys win:**
+1. **No typos** - Can't misspell a direction
+2. **Discoverable** - See all options immediately
+3. **Familiar** - Every developer knows arrow navigation
+4. **Fast** - Two keystrokes: arrow + enter
+
+### Universal Commands: Always Visible
+
+But we kept the power of commands for experts:
+
+```python
+# At ANY point during debugging:
+/menu      # Back to main menu
+/continue  # Resume execution
+?          # Show help
+```
+
+These appear in **every** screen footer:
+```
+💡 Commands: /menu /continue • Press ? for help
+```
+
+**The principle: Simple by default, powerful when ready.**
+
+## The Five Debugging Modes (Final)
+
+We designed five debugging modes, each progressively more powerful:
+
+### 0. Menu (Default - Visual Discovery)
+```
+The menu itself is a mode - visual discovery of all options
+Arrow keys OR shortcuts
+No memorization required
+```
+
+### 1. Continue (Default - Simple)
+```
+Just resume execution
+→ No learning required
+→ Fast escape hatch
+```
+
+### 2. AI Help (Powerful)
+```python
+# Ask questions in natural language
+"Why did this tool fail?"
+"What does the current state look like?"
+"How can I fix the query parameter?"
+
+# AI has FULL context:
+# - Agent's task
+# - Tool history
+# - Current state
+# - Error messages
+```
+
+### 3. Python Edit (Expert)
+```python
+# Full Python REPL at breakpoint
+>>> query  # Inspect variables
+'broken search'
+
+>>> query = "better search"  # Modify
+>>> tool_result = search(query)  # Test
+>>> # Exit to continue with changes
+```
+
+### 4. Step Mode (Debug Everything)
+```
+🔍 Step Mode: ON
+Pause at EVERY tool call
+
+[search] → Paused
+[calculate] → Paused
+[write_file] → Paused
+
+Perfect for tracing complex flows
+```
+
+## Solving the Learning Curve Problem
+
+The original concern: **"My only concern is that the learning curve should be simple and clear."**
+
+Our solutions:
+
+### 1. Visual Mode Indicators
+```python
+# Normal mode
+Agent paused at: search
+┌─────────────────────────┐
+│  ❯ Continue             │
+│    AI Help              │
+└─────────────────────────┘
+
+# Step Mode active
+🔍 STEP MODE: Pausing at EVERY tool
+Agent paused at: search
+┌─────────────────────────┐
+│  ❯ Continue (step)      │
+│    Exit Step Mode       │
+└─────────────────────────┘
+```
+
+Mode changes are **visually obvious**, not just text.
+
+### 2. Always-Visible Tips
+```
+💡 Use ↑↓ arrows • Enter to select • Press ? for help
+```
+
+Every screen reminds you how to navigate. No memorization needed.
+
+### 3. Contextual Help
+```python
+# Press ? anywhere
+─────────── Help ───────────
+At menu: Use arrows to navigate
+In AI Help: Ask natural language questions
+In Python: Full REPL, 'exit' to continue
+Commands: /menu /continue always work
+```
+
+Help is context-aware - shows what matters NOW.
+
+### 4. Progressive Disclosure
+```
+First use: See Continue, AI Help (simple)
+Get curious: Discover Python Edit (power)
+Deep debug: Enable Step Mode (expert)
+```
+
+You can't be overwhelmed by options you don't see yet.
+
+## What We Explicitly Rejected
+
+### ❌ Complex Command Syntax
+```bash
+# NO
+co debug --breakpoint search --condition "query='test'" --on-error retry
+```
+Too much to remember. Too easy to break.
+
+### ❌ Configuration Files
+```yaml
+# NO
+debug:
+  breakpoints:
+    - tool: search
+      condition: query == 'test'
+```
+Configuration is code you can't debug.
+
+### ❌ Separate Debug Tool
+```bash
+# NO
+co debug agent.py   # Different tool, different context
+```
+Debugging should be built-in, not bolted-on.
+
+### ❌ Typed Commands at Breakpoint
+```
+# NO
+(debug) > inspect
+(debug) > retry --modify
+(debug) > step
+```
+Menu navigation is more intuitive than command recall.
+
+## The Unix and Steve Jobs Principles We Applied
+
+The question "What would Unix creators or Steve Jobs design?" guided our final iteration. Here's how we applied their principles:
+
+### From Unix Philosophy (Ken Thompson, Dennis Ritchie)
+
+#### 1. Make Each Program Do One Thing Well
+```
+Continue mode = Continue only (single purpose)
+AI Help = Answer questions only (single purpose)
+Python Edit = Modify variables only (single purpose)
+View Trace = Show history only (single purpose)
+Step Mode = Toggle pause behavior only (single purpose)
+```
+
+Each mode has ONE job. No overlap, no confusion.
+
+#### 2. Expect Output to Become Input (Composition)
+```
+Menu → AI mode → /menu → Menu
+Menu → Python mode → /continue → Resume
+Menu → View Trace → [Enter] → Menu
+```
+
+Modes compose naturally. Output of one flows to input of another.
+
+#### 3. Design Software to Be Tried Early
+```
+We shipped:
+  Week 1: Basic menu + continue
+  Week 2: Added AI Help
+  Week 3: Added Python Edit
+  Week 4: Added Step Mode
+```
+
+Validate early, iterate based on feedback, ship incrementally.
+
+#### 4. Use Software Leverage (Build on Existing Tools)
+```python
+from rich.console import Console  # Terminal UI (don't reinvent)
+from code import InteractiveConsole  # Python REPL (reuse)
+```
+
+We composed from existing, proven tools rather than building everything from scratch.
+
+### From Steve Jobs (Apple Design Philosophy)
+
+#### 1. Simplicity is the Ultimate Sophistication
+```
+4 modes → Too complex
+3 modes → Still complex
+5 modes BUT menu-driven → Simple
+
+The menu makes complexity simple by making it VISUAL.
+```
+
+More modes, but simpler experience. Visual beats cognitive load.
+
+#### 2. Focus Means Saying No
+```
+We said NO to:
+- Typed commands at breakpoint
+- Configuration files
+- Separate CLI tool
+- Mode switching complexity
+
+We said YES to:
+- Menu navigation
+- Visual discovery
+- Press Enter to continue
+```
+
+Every "no" made room for a better "yes."
+
+#### 3. Design is How It Works, Not How It Looks
+```
+The menu isn't decoration - it IS the debugging interface
+Arrow navigation isn't a feature - it IS how you debug
+Tips aren't help text - they ARE the documentation
+```
+
+Form follows function. The interface IS the experience.
+
+#### 4. Make It Intuitive, Not Learnable
+```
+Learnable: "Read the docs to understand modes"
+Intuitive: "See menu, press arrow, select option"
+
+First-time users succeed without docs = intuitive
+```
+
+Zero learning curve for basic usage. That's intuitive design.
+
+### How These Principles Shaped Decisions
+
+**Decision: Menu vs Typed Commands**
+- Unix: Visual listing (like `ls`) beats command recall
+- Jobs: See all options immediately (no memorization)
+- **Result:** Menu with arrow navigation
+
+**Decision: Press Enter to Continue**
+- Unix: Default behavior should be simplest (like `less`)
+- Jobs: Essential action should be effortless
+- **Result:** Enter = continue (0 friction)
+
+**Decision: `/menu` and `/continue` Everywhere**
+- Unix: Universal commands work everywhere (like `Ctrl+C`)
+- Jobs: No dead ends, always a way out
+- **Result:** Universal escape hatches
+
+**Decision: Full Names + Shortcuts**
+- Unix: Teach with long flags (`--verbose`), reward with short (`-v`)
+- Jobs: Discoverability first, efficiency second
+- **Result:** `/ai-ask` or `/ai` - both work
+
+## The Implementation Philosophy
+
+### 1. @xray Decorator: Opt-In Breakpoints
+```python
+@xray  # This tool becomes a breakpoint
+def search(query: str) -> str:
+    return find_results(query)
+
+agent = Agent("assistant", tools=[search])
+agent.auto_debug()  # Pauses at @xray tools
+```
+
+**Why @xray?**
+- Self-documenting (code shows what's debuggable)
+- No runtime overhead when auto_debug() not called
+- Composable with other decorators
+
+### 2. agent.auto_debug(): Session-Based
+```python
+# Debugging is per-session, not global
+agent1.auto_debug()  # Debug this agent
+agent2.input("task")  # This one runs normally
+```
+
+No global state. No surprise behaviors.
+
+### 3. Rich Terminal UI: Native Experience
+```python
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+# Beautiful, functional, standard
+console.print(Panel("Agent paused", style="blue"))
+```
+
+Using Rich library:
+- Professional terminal UI
+- Wide compatibility
+- Familiar to Python developers
+
+## The Trade-offs We Made
+
+### We Chose: Intuitive > Powerful CLI
+
+**Pro:**
+- First-time users succeed immediately
+- Menu navigation is self-documenting
+- Arrow keys can't be mistyped
+- Progressive disclosure prevents overwhelm
+
+**Con:**
+- Menu navigation is slower than typed commands (for experts)
+- Requires interactive terminal (won't work in pure scripts)
+
+**Our stance:** 99% of debugging happens interactively. The 1% edge case (non-interactive) can use logging/print debugging.
+
+### We Chose: Session-Based > Configuration-Based
+
+**Pro:**
+- `agent.auto_debug()` is explicit and obvious
+- No hidden config files to debug
+- Works in any environment (REPL, notebook, script)
+
+**Con:**
+- Have to call `.auto_debug()` on each agent
+- No "debug all agents" global mode
+
+**Our stance:** Explicit > Implicit. Knowing which agents are debugged prevents surprises.
+
+### We Chose: @xray Decorator > Auto-Breakpoint All
+
+**Pro:**
+- Developer controls what's debuggable
+- No performance impact on non-decorated tools
+- Clear visual indicator in code
+
+**Con:**
+- Requires adding decorator to tools
+- Can't debug tools you don't control (external libraries)
+
+**Our stance:** 95% of debugging is on your own tools. For external tools, wrap them.
+
+## Lessons Learned from Four Iterations
+
+### 1. Listen to User Feedback - It Saves You
+- **Iteration 1:** *"Too complicated"* → Simplified from 4 modes
+- **Iteration 2:** *"Agent should default have a mode"* → Made agent-first explicit
+- **Iteration 3:** *"AI Ask more intuitive"* → Clarified naming
+- **Final:** *"What would Unix/Jobs design?"* → Eliminated complexity
+
+**We almost built the wrong thing - four times. Feedback saved us every time.**
+
+### 2. User Journey > Feature List
+Asking "What does a developer WANT?" (continue execution) led to better design than "What CAN we build?" (complex modes).
+
+**Default should be the most common action, not the most powerful.**
+
+### 3. Intuitive > Learnable
+- `agent.auto_debug()` - Discovered via autocomplete (intuitive)
+- Arrow keys - Everyone knows these (intuitive)
+- Menu - See options visually (intuitive)
+- CLI commands - Require docs and practice (learnable)
+
+**If it requires documentation for basic usage, it's not intuitive enough.**
+
+### 4. More Features ≠ Better UX
+We went from:
+- 4 modes (complex)
+- 2-3 modes (simpler)
+- 5 modes BUT menu-driven (simplest!)
+
+**Visual discovery makes complexity manageable. Hide it behind a good interface.**
+
+### 5. Progressive Disclosure Works Perfectly
+```
+First use: See menu, press Enter (10 seconds to understand)
+Get curious: Try 'a' for AI help (discover power)
+Need control: Discover 'e' for Python (expert mode)
+Deep debug: Enable step mode (maximum visibility)
+```
+
+**Reveal complexity gradually. Never overwhelm upfront.**
+
+### 6. Consistent Patterns Enable Muscle Memory
+- All commands use `/` prefix
+- All modes show tips
+- All screens offer `/menu` and `/continue`
+
+**Consistency reduces cognitive load. Exceptions require thinking.**
+
+### 7. Default Matters More Than Anything
+Press Enter to continue - the simplest possible action.
+
+**If the default is perfect, 80% of users never need advanced features.**
+
+### 8. Ask "What Would Masters Design?"
+Unix and Steve Jobs principles aren't abstract - they're actionable:
+- Do one thing well → Single purpose per mode
+- Eliminate unnecessary → Removed mode switching
+- Make it intuitive → Visual menu, not commands
+
+**Learn from the best, apply to your domain.**
+
+## The Implementation Phases
+
+We broke this into a 6-phase MVP-first approach:
+
+### Phase 1: Core Infrastructure (Week 1)
+- Breakpoint detection system
+- Interactive pause/continue
+- Basic menu with arrow keys
+
+### Phase 2-3: Menu & Modes (Week 2)
+- Full menu navigation
+- AI Help Mode implementation
+- View Trace functionality
+
+### Phase 4-5: Advanced Features (Week 3)
+- Python Edit Mode (REPL at breakpoint)
+- Step Mode (pause at ALL tools)
+- Command system (/menu, /continue, ?)
+
+### Phase 6: Polish (Week 4)
+- Error handling & edge cases
+- Comprehensive documentation
+- Tutorial videos
+
+**Target: 4 weeks from design to shipped.**
+
+## Future Possibilities This Enables
+
+The menu-based architecture makes future enhancements natural:
+
+### Remote Debugging (Future)
+```
+┌─────────────────────────┐
+│  ❯ Continue             │
+│    AI Help              │
+│    Remote Inspect ← NEW │
+└─────────────────────────┘
+
+# Debug agent running on server
+# Menu item connects to remote session
+```
+
+### Visual Debugger (Future)
+```
+Menu system stays the same
+Add: Export state to web UI
+Click menu items in browser instead of terminal
+```
+
+### Collaborative Debugging (Future)
+```
+Multiple developers join same debug session
+Menu shows who's controlling
+Vote on which option to select
+```
+
+But we ship Phase 1 first. **Validate before expanding.**
+
+## The Core Principles
+
+1. **Intuitive > Learnable** - No manual required
+2. **Menu > Commands** - Visual beats recall
+3. **Progressive Disclosure** - Simple first, power later
+4. **Always Visible Help** - No memorization needed
+5. **Session-Based** - Explicit beats implicit
+6. **@xray Decorator** - Opt-in beats auto-everything
+
+## Conclusion: The Journey from Complex to Simple
+
+We almost built the wrong thing - **five times**:
+
+1. **CLI tool** - Required learning commands, broke Python flow
+2. **4-mode system** - Too complicated, high learning curve
+3. **Prefix characters** - Not discoverable, unclear purpose
+4. **Mode prompts** - Better but still needed work
+5. **Agent-first menu** - Finally got it right ✅
+
+Each iteration taught us something:
+- **Iteration 1 → 2:** Reduce complexity (4 modes → simpler)
+- **Iteration 2 → 3:** Make default obvious (agent-first)
+- **Iteration 3 → 4:** Clarify naming (AI Ask vs ai>)
+- **Applied Unix/Jobs:** Eliminate unnecessary, focus on essence
+
+**The final design:**
+- `agent.auto_debug()` - One method to remember
+- Press Enter - Simplest action (continue)
+- Arrow keys - Navigation everyone knows
+- Menu - Visual discovery (no memorization)
+- Shortcuts - Power when ready (progressive disclosure)
+- Universal `/commands` - Escape hatches everywhere
+
+**The result: Debugging that feels natural, not learned.**
+
+### What Made the Difference
+
+**User feedback at every stage:**
+- *"Too complicated"* - Led to simplification
+- *"Learning curve should be simple"* - Led to progressive disclosure
+- *"Agent should be primary"* - Led to agent-first design
+- *"What would Unix/Jobs design?"* - Led to final breakthrough
+
+**Applying timeless principles:**
+- Unix: Do one thing well, compose simply
+- Steve Jobs: Eliminate unnecessary, make it intuitive
+- Both: Default action should be effortless
+
+**The willingness to iterate:**
+- Five complete redesigns before shipping
+- Each rejected design taught us something
+- Final design emerged from learning, not planning
+
+### The Core Principles That Won
+
+1. **Intuitive > Learnable** - No manual required for basic usage
+2. **Menu > Commands** - Visual discovery beats command recall
+3. **Progressive Disclosure** - Start simple, reveal power gradually
+4. **Always Visible Help** - Zero memorization needed
+5. **Agent-First** - Default matches most common action
+6. **Consistent Patterns** - All `/` commands work everywhere
+
+---
+
+*"Simplicity is the ultimate sophistication." - Leonardo da Vinci*
+
+*We iterated five times to find the simplest solution.*
+
+## Meta: How This Design Really Happened
+
+This design decision documents a rare journey of honest iteration:
+
+1. **Rejected CLI** (wrong tool for the job)
+2. **Rejected 4-mode design** (too complex)
+3. **Rejected prefix characters** (not discoverable)
+4. **Rejected mode prompts** (still unclear)
+5. **Asked "What would masters design?"** (breakthrough)
+6. **Applied Unix + Jobs principles** (final design)
+
+**The turning point:** Asking "What would Unix creators or Steve Jobs design?" forced us to apply timeless principles instead of following our assumptions.
+
+**The uncomfortable truth:** We were wrong four times before getting it right. And that's okay.
+
+**The real lesson:** The best design decision is often admitting your previous one was wrong.
+
+### What This Means for ConnectOnion
+
+This isn't just about auto-debug. It's about our design process:
+
+1. **Start with user problems** (invisible agent behavior)
+2. **Prototype solutions** (CLI, modes, prompts)
+3. **Get user feedback early** (reject what doesn't work)
+4. **Apply timeless principles** (Unix, Jobs, great designers)
+5. **Iterate until simple** (5 tries for auto-debug)
+6. **Ship when intuitive** (zero learning curve achieved)
+
+**We don't just build features. We solve problems through iteration.**
+
+Every design decision should go through this process. Auto-debug is the template.
+
+---
+
+*This document evolved alongside the design - from initial CLI concept to final menu-based REPL. The edits and iterations you see in the git history mirror the design iterations themselves. Meta-documentation at its finest.*