Design Decision

Auto-Debug Design Evolution

Five iterations to simplicity: How user feedback and timeless design principles shaped our interactive debugging experience

October 6, 2025 · 12 min read

The Problem: Debugging AI Agents in the Dark

AI agents make decisions we can't see. They call tools, process results, iterate through problems - all invisible to developers. When something goes wrong, you're left guessing.

main.py

agent = Agent("assistant", tools=[search, send_email])
agent.input("Send email to John")
# *mysterious processing happens*
# Wrong email sent... but why? what happened?

We needed a way to see inside agent execution, understand decisions, and test "what if" scenarios. The question was: how?

Iteration 1: The Complex Four-Mode System ❌

Our first instinct was to build something comprehensive - a debugging system with four distinct modes for different tasks.

code

🔍 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"

Lesson #1:

More features ≠ better UX. High learning curve before being productive.

Iteration 2: Prefix-Based Mode Switching ❌

We simplified by using prefix characters to indicate different targets:

code

agent> Hello                    # Send to agent
agent> ? why did it fail        # Ask AI for help
agent> >>> result = []          # Python code

User Feedback:

"When we do auto-debug, the input to the agent should default have a mode"

Lesson #2:

Symbolic shortcuts (?, >>>) require learning. Not discoverable without docs.

Iteration 3: Mode Indicators with Prompts 🟡

We added clear, named mode indicators to show where input goes:

code

agent> Send email to John       # To agent

ai> why did it send wrong email # To AI

>>> result = "correct@email"    # Python

User Feedback:

"The AI should be something more intuitive like 'AI Ask' or something like that"

Lesson #3:

Names matter. "AI" is ambiguous - "AI Ask" is self-explanatory. Progress made but still not simple enough.

The Breakthrough Question

"What would Unix creators or Steve Jobs design?"

This forced us to apply timeless design principles instead of following our assumptions:

Unix Philosophy

• Do one thing well
• Compose simply
• Ship early, validate

Steve Jobs

• Eliminate unnecessary
• Focus on essence
• Intuitive over learnable

Iteration 4: Agent-First Menu ✅

The final design that actually works:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@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:

✅ Agent-first by default - Press Enter to continue (simplest action)
✅ Progressive disclosure - See options, discover gradually
✅ Multiple input methods - Arrow keys (beginner) OR shortcuts (expert)
✅ Always visible help - Tips on every screen, zero memorization
✅ Universal commands - /menu and /continue work everywhere
✅ No dead ends - Always a way back or forward

Key Lessons from Five Iterations

1. Listen to User Feedback

We almost built the wrong thing FIVE times. User feedback redirected us every time. Without it, we'd have shipped a complex, unusable debugger.

2. Ask "What Would Masters Design?"

Unix and Steve Jobs principles aren't abstract - they're actionable. Single purpose per mode. Eliminate unnecessary. Visual over cognitive load.

3. Default Action Should Be Effortless

Most users just want to continue. Make that one keystroke: Enter. If the default is perfect, 80% never need advanced features.

4. Visual Discovery >Command Recall

Menu navigation beats typed commands for discoverability. See all options immediately. No memorization required.

5. Iteration Beats Planning

We couldn't have designed the final version first. Each failure taught us something essential. Embrace iteration.

Try It Yourself

main.py

from connectonion import Agent
from connectonion.decorators import xray

@xray
def search_emails(query: str):
    return api.search(query)

agent = Agent("assistant", tools=[search_emails])
agent.auto_debug()  # Launch interactive debugging

Press Enter to continue, or explore the menu. No manual required.

Progressive Disclosure CLI

Coming Soon Features