create-merlin-brain 2.3.2 → 2.4.0

package/files/loop/merlin-loop.sh

@@ -37,6 +37,12 @@ source "$SCRIPT_DIR/lib/state.sh"
 source "$SCRIPT_DIR/lib/safety.sh"
 source "$SCRIPT_DIR/lib/progress.sh"
 source "$SCRIPT_DIR/lib/context.sh"
+source "$SCRIPT_DIR/lib/modes.sh"
+source "$SCRIPT_DIR/lib/sights.sh" 2>/dev/null || true       # Sights integration
+source "$SCRIPT_DIR/lib/agents.sh" 2>/dev/null || true      # Agent profiles and routing
+source "$SCRIPT_DIR/lib/boot.sh" 2>/dev/null || true        # Boot sequence
+source "$SCRIPT_DIR/lib/session-end.sh" 2>/dev/null || true # Session end protocol
+source "$SCRIPT_DIR/lib/tui.sh" 2>/dev/null || true         # Interactive TUI
 
 # Defaults (can be overridden via config.json or env vars)
 MAX_ITERATIONS="${MERLIN_MAX_ITERATIONS:-50}"
@@ -46,6 +52,14 @@ RATE_LIMIT_PER_HOUR="${MERLIN_RATE_LIMIT:-100}"
 CLOUD_SYNC="${MERLIN_CLOUD_SYNC:-true}"
 NOTIFY_ON_COMPLETE="${MERLIN_NOTIFY:-true}"
 
+# Loop mode configuration (auto, interactive, hybrid)
+LOOP_MODE="${MERLIN_LOOP_MODE:-hybrid}"
+PAUSE_INTERVAL="${MERLIN_PAUSE_INTERVAL:-5}"  # Pause every N tasks in hybrid mode
+
+# Timeout configuration
+PAUSE_TIMEOUT="${MERLIN_PAUSE_TIMEOUT:-300}"  # 5 minutes default
+TIMEOUT_ENABLED="${MERLIN_TIMEOUT_ENABLED:-true}"
+
 # Native Claude Tasks integration
 # This enables cross-session task coordination - all spawned instances share task state
 # If not provided, we'll generate one based on project directory
@@ -159,11 +173,13 @@ show_launch_screen() {
   echo ""
   echo -e "  ${YELLOW}${BOLD}▸ STARTING AUTONOMOUS BUILD${RESET}"
   echo ""
-  echo -e "  ${CYAN}Mode:${RESET}           ${BOLD}$mode${RESET}"
+  echo -e "  ${CYAN}Command:${RESET}        ${BOLD}$mode${RESET}"
+  echo -e "  ${CYAN}Loop Mode:${RESET}      ${BOLD}$(get_mode_display)${RESET}"
   echo -e "  ${CYAN}AI:${RESET}             ${BOLD}$ai_cli${RESET}"
   echo -e "  ${CYAN}Max Iterations:${RESET} ${BOLD}$MAX_ITERATIONS${RESET}"
   echo -e "  ${CYAN}Cooldown:${RESET}       ${BOLD}${COOLDOWN_SECONDS}s${RESET} between iterations"
   echo -e "  ${CYAN}Circuit Breaker:${RESET}${BOLD}$CIRCUIT_BREAKER_THRESHOLD${RESET} errors to stop"
+  echo -e "  ${CYAN}Pause Timeout:${RESET} ${BOLD}$(get_timeout_status 2>/dev/null || echo "${PAUSE_TIMEOUT}s")${RESET}"
   echo -e "  ${CYAN}Cloud Sync:${RESET}     ${BOLD}$CLOUD_SYNC${RESET}"
   echo -e "  ${CYAN}Task List:${RESET}      ${BOLD}${TASK_LIST_ID:-auto}${RESET}"
   echo ""
@@ -198,6 +214,7 @@ show_launch_screen() {
 
 init_loop() {
   mkdir -p "$LOOP_DIR"
+  LOOP_START_TIME=$(date +%s)
 
   # Check for existing lock (another loop running)
   if [ -f "$LOCK_FILE" ]; then
@@ -236,9 +253,95 @@ init_loop() {
   if [ "$CLOUD_SYNC" = "true" ]; then
     sync_from_cloud
   fi
+
+  # Initialize Sights (includes worker registration)
+  if type init_sights &> /dev/null; then
+    init_sights
+    echo -e "${GREEN}✓ Sights: Connected${RESET}"
+  fi
+
+  # Check for cloud checkpoint and offer restore
+  if type fetch_checkpoint &> /dev/null; then
+    local checkpoint_json
+    checkpoint_json=$(fetch_checkpoint 2>/dev/null || echo "")
+
+    if [ -n "$checkpoint_json" ]; then
+      local has_checkpoint
+      has_checkpoint=$(echo "$checkpoint_json" | jq -r '.checkpoint != null' 2>/dev/null || echo "false")
+
+      if [ "$has_checkpoint" = "true" ]; then
+        echo ""
+        echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+        echo -e "${BOLD}📍 Cloud Checkpoint Found${RESET}"
+        echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+        format_checkpoint "$checkpoint_json"
+        echo ""
+
+        if [ "${QUIET:-false}" != "true" ] && [ -t 0 ]; then
+          echo -e "${YELLOW}Resume from this checkpoint?${RESET}"
+          echo -e "  [${BOLD}y${RESET}] Yes, continue from checkpoint"
+          echo -e "  [${BOLD}n${RESET}] No, start fresh"
+          echo -ne "  Choice: "
+          read -r choice
+
+          if [ "$choice" = "y" ] || [ "$choice" = "Y" ]; then
+            # Restore checkpoint state to local state
+            local phase task summary
+            phase=$(echo "$checkpoint_json" | jq -r '.checkpoint.currentPhase // empty')
+            task=$(echo "$checkpoint_json" | jq -r '.checkpoint.currentTask // empty')
+            summary=$(echo "$checkpoint_json" | jq -r '.checkpoint.summary // empty')
+
+            if [ -n "$phase" ]; then
+              set_state_value "plan.current_phase" "$phase"
+            fi
+            if [ -n "$task" ] && [ "$task" != "null" ]; then
+              set_state_value "plan.current_task" "$task"
+            fi
+
+            echo -e "${GREEN}✓ Checkpoint restored${RESET}"
+            echo ""
+          fi
+        fi
+      fi
+    fi
+  fi
+
+  # Start worker heartbeat in background
+  if type start_heartbeat &> /dev/null; then
+    start_heartbeat 30  # Send heartbeat every 30 seconds
+    echo -e "${BLUE}Worker heartbeat started${RESET}"
+  fi
+
+  # Check for other active workers (multi-user awareness)
+  if type get_active_workers &> /dev/null; then
+    local workers_json
+    workers_json=$(get_active_workers 2>/dev/null || echo "")
+
+    if [ -n "$workers_json" ]; then
+      local worker_count
+      worker_count=$(echo "$workers_json" | jq -r '.count // 0' 2>/dev/null || echo "0")
+
+      if [ "$worker_count" -gt 1 ]; then
+        echo ""
+        echo -e "${YELLOW}⚠️  ${worker_count} workers active on this repository${RESET}"
+        echo -e "${YELLOW}   Be aware of potential task conflicts.${RESET}"
+        echo ""
+      fi
+    fi
+  fi
 }
 
 cleanup() {
+  # Stop worker heartbeat
+  if type stop_heartbeat &> /dev/null; then
+    stop_heartbeat
+  fi
+
+  # Run quick session end on cleanup (commit + checkpoint without verbose output)
+  if type session_end_quick &> /dev/null; then
+    session_end_quick "Loop stopped (cleanup)" "" 2>/dev/null || true
+  fi
+
   rm -f "$LOCK_FILE"
 
   # Final cloud sync
@@ -252,16 +355,36 @@ run_iteration() {
   local iteration="$2"
   local prompt_file="$SCRIPT_DIR/prompts/PROMPT_${mode}.md"
 
-  echo -e "\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
-  echo -e "${BOLD}Iteration $iteration / $MAX_ITERATIONS${RESET} (mode: $mode)"
-  echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  # Get current task info
+  local current_task_desc task_completed task_total
+  current_task_desc=$(get_state_value "plan.current_task_desc" 2>/dev/null || echo "Continue with next task")
+  task_completed=$(get_state_value "plan.completed_tasks" 2>/dev/null || echo "0")
+  task_total=$(get_state_value "plan.total_tasks" 2>/dev/null || echo "0")
+
+  # TUI: Show task header with progress bar (replaces basic echo)
+  if type show_task_header &> /dev/null; then
+    show_task_header "$iteration" "$MAX_ITERATIONS" "$current_task_desc" "${BOOT_SELECTED_AGENT:-claude}"
+    if [ "$task_total" -gt 0 ] && type draw_progress_bar &> /dev/null; then
+      draw_progress_bar "$task_completed" "$task_total" 50 "  Tasks"
+      echo ""
+    fi
+  else
+    echo -e "\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+    echo -e "${BOLD}Iteration $iteration / $MAX_ITERATIONS${RESET} (mode: $mode)"
+    echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  fi
+
+  # Run Merlin Pro Boot Sequence (5 phases)
+  if type run_boot_sequence &> /dev/null; then
+    run_boot_sequence "$current_task_desc"
+  fi
 
   # Record iteration start
   local start_time
   start_time=$(date +%s)
   record_iteration_start "$iteration" "$mode"
 
-  # Build the prompt with current state
+  # Build the prompt with current state and boot context
   local full_prompt
   full_prompt=$(build_prompt "$mode")
 
@@ -269,13 +392,25 @@ run_iteration() {
   local output
   local exit_code=0
 
-  echo -e "${BLUE}Spawning Claude with fresh context...${RESET}"
-  echo -e "${BLUE}Task list: ${TASK_LIST_ID}${RESET}"
+  # Route to the specialist agent selected by boot sequence
+  local agent_cli_name="merlin"
+  if [ -n "${BOOT_SELECTED_AGENT:-}" ] && type get_agent_cli_name &> /dev/null; then
+    agent_cli_name=$(get_agent_cli_name "$BOOT_SELECTED_AGENT")
+  fi
+
+  local agent_display_name="$agent_cli_name"
+  if type get_agent_display_name &> /dev/null && [ -n "${BOOT_SELECTED_AGENT:-}" ]; then
+    agent_display_name=$(get_agent_display_name "$BOOT_SELECTED_AGENT")
+  fi
+
+  echo -e "${BLUE}Spawning Claude as ${BOLD}${agent_display_name}${RESET}${BLUE}...${RESET}"
+  echo -e "${BLUE}Agent: --agent ${agent_cli_name} | Task list: ${TASK_LIST_ID}${RESET}"
 
   # Capture output and exit code
   # CLAUDE_CODE_TASK_LIST_ID enables cross-session task coordination
+  # --agent routes to the specialist selected by boot sequence
   set +e
-  output=$(CLAUDE_CODE_TASK_LIST_ID="$TASK_LIST_ID" claude --agent merlin --output-format stream-json 2>&1 <<< "$full_prompt")
+  output=$(CLAUDE_CODE_TASK_LIST_ID="$TASK_LIST_ID" claude --agent "$agent_cli_name" --output-format stream-json 2>&1 <<< "$full_prompt")
   exit_code=$?
   set -e
 
@@ -288,30 +423,110 @@ run_iteration() {
 
   # Parse output for signals
   if echo "$output" | grep -q "EXIT_SIGNAL"; then
+    # Run session end protocol before completing
+    if type session_end_protocol &> /dev/null; then
+      session_end_protocol "$current_task_desc" "" ""
+    fi
     echo -e "\n${GREEN}${BOLD}EXIT_SIGNAL detected - Loop complete!${RESET}"
     return 0
   fi
 
-  if echo "$output" | grep -q "CHECKPOINT_SIGNAL"; then
+  # Count tasks completed (for pause interval)
+  local task_count
+  task_count=$(get_state_value "plan.completed_tasks" 2>/dev/null || echo "0")
+
+  # Check if we should pause based on mode
+  if should_pause "$output" "$task_count"; then
+    local pause_result
+    handle_pause "$output" "$iteration" "$task_count"
+    pause_result=$?
+
+    case $pause_result in
+      0)  # Continue
+        ;;
+      1)  # Quit
+        return 0
+        ;;
+      2)  # Skip task
+        return 2
+        ;;
+    esac
+  fi
+
+  # Legacy checkpoint handling (for backward compatibility)
+  if echo "$output" | grep -q "CHECKPOINT_SIGNAL" && [ "$LAST_PAUSE_REASON" != "checkpoint" ]; then
     echo -e "\n${YELLOW}${BOLD}CHECKPOINT_SIGNAL detected - User input needed${RESET}"
     handle_checkpoint "$output"
     return 2  # Continue after checkpoint
   fi
 
   if [ $exit_code -ne 0 ]; then
+    # TUI: Show task failure
+    if type show_task_complete &> /dev/null; then
+      show_task_complete "$current_task_desc" "$duration" "error"
+    fi
     echo -e "\n${RED}Claude exited with error code: $exit_code${RESET}"
     record_error "$iteration" "$exit_code" "$output"
     return 1
   fi
 
+  # ═══════════════════════════════════════════════════════════════════════════
+  # MERLIN GUARANTEE: Verify Claude used Sights during iteration
+  # ═══════════════════════════════════════════════════════════════════════════
+  local sights_used=true
+  if ! echo "$output" | grep -qiE "merlin_get_context|merlin_search|merlin_find_files|SIGHTS|merlin_get_conventions|merlin_check_freshness|merlin_get_brief"; then
+    sights_used=false
+    echo ""
+    echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+    echo -e "${YELLOW}⚠️  MERLIN GUARANTEE WARNING${RESET}"
+    echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+    echo -e "${YELLOW}Claude did not use Merlin Sights during this iteration.${RESET}"
+    echo -e "${YELLOW}Output may lack codebase awareness. Proceeding with caution.${RESET}"
+    echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+    echo ""
+  fi
+
   # Update state from Claude's output
   parse_and_update_state "$output"
 
+  # ═══════════════════════════════════════════════════════════════════════════
+  # SESSION END PROTOCOL: Enforced after every iteration
+  # Replaces ad-hoc inline calls with the formal 5-step protocol
+  # ═══════════════════════════════════════════════════════════════════════════
+  local current_task
+  current_task=$(get_state_value "plan.current_task" 2>/dev/null || echo "")
+
+  if type session_end_protocol &> /dev/null; then
+    # Full protocol: check changes → commit → push → record to Sights → checkpoint
+    session_end_protocol "$current_task_desc" "$current_task" ""
+  else
+    # Fallback: ad-hoc calls if session-end.sh didn't load
+    if type record_last_commit &> /dev/null; then
+      record_last_commit "$current_task" "claude" "loop-agent" &
+    fi
+    if type save_checkpoint &> /dev/null; then
+      local current_phase working_files
+      current_phase=$(get_state_value "plan.current_phase" 2>/dev/null || echo "")
+      working_files=$(get_state_value "plan.working_files" 2>/dev/null || echo "[]")
+      save_checkpoint "Completed iteration $iteration" "$current_phase" "$current_task" "$working_files" "merlin-loop" &
+    fi
+  fi
+
+  # Update worker heartbeat with current task
+  if type worker_heartbeat &> /dev/null; then
+    worker_heartbeat "$current_task" &
+  fi
+
   # Cloud sync after each iteration
   if [ "$CLOUD_SYNC" = "true" ]; then
     sync_to_cloud_async
   fi
 
+  # TUI: Show task completion
+  if type show_task_complete &> /dev/null; then
+    show_task_complete "$current_task_desc" "$duration" "success"
+  fi
+
   return 2  # Continue loop
 }
 
@@ -336,6 +551,33 @@ $state
 \`\`\`
 "
 
+  # Inject recent changes from Sights (if available)
+  if type fetch_recent_changes &> /dev/null; then
+    local recent_changes
+    recent_changes=$(fetch_recent_changes 2>/dev/null || echo "")
+    if [ -n "$recent_changes" ] && [ "$recent_changes" != "# Recent Changes: Not available"* ]; then
+      prompt="$prompt
+
+---
+$recent_changes
+"
+    fi
+  fi
+
+  # Inject boot context (agent guidance, skills, trajectory)
+  if type get_boot_context &> /dev/null; then
+    local boot_context
+    boot_context=$(get_boot_context)
+    if [ -n "$boot_context" ]; then
+      prompt="$prompt
+
+---
+## Boot Context (from Merlin Pro)
+
+$boot_context"
+    fi
+  fi
+
   # Inject relevant context from memory
   local context
   context=$(get_relevant_context "$mode")
@@ -419,7 +661,16 @@ main_loop() {
     case $result in
       0)
         # EXIT_SIGNAL - complete
-        echo -e "\n${GREEN}${BOLD}Loop completed successfully after $iteration iterations${RESET}"
+        # TUI: Show beautiful completion banner
+        if type show_loop_complete &> /dev/null; then
+          local stats_completed stats_errors
+          stats_completed=$(get_state_value "plan.completed_tasks" 2>/dev/null || echo "$iteration")
+          stats_errors=$(get_state_value "plan.total_errors" 2>/dev/null || echo "0")
+          local total_elapsed=$(($(date +%s) - ${LOOP_START_TIME:-$(date +%s)}))
+          show_loop_complete "$stats_completed" "$total_elapsed" "$stats_errors"
+        else
+          echo -e "\n${GREEN}${BOLD}Loop completed successfully after $iteration iterations${RESET}"
+        fi
         if [ "$NOTIFY_ON_COMPLETE" = "true" ]; then
           send_notification "Merlin Loop Complete" "Finished after $iteration iterations"
         fi
@@ -444,6 +695,14 @@ main_loop() {
     fi
   done
 
+  # TUI: Show completion even on max iterations
+  if type show_loop_complete &> /dev/null; then
+    local stats_completed stats_errors
+    stats_completed=$(get_state_value "plan.completed_tasks" 2>/dev/null || echo "0")
+    stats_errors=$(get_state_value "plan.total_errors" 2>/dev/null || echo "0")
+    local total_elapsed=$(($(date +%s) - ${LOOP_START_TIME:-$(date +%s)}))
+    show_loop_complete "$stats_completed" "$total_elapsed" "$stats_errors"
+  fi
   echo -e "\n${YELLOW}${BOLD}Max iterations ($MAX_ITERATIONS) reached${RESET}"
   echo "Resume with: merlin-loop resume --max $((MAX_ITERATIONS + 50))"
   show_summary
@@ -478,22 +737,56 @@ usage() {
   echo "  reset      Reset loop state (keeps history)"
   echo ""
   echo "Options:"
+  echo "  --mode MODE     Loop mode: auto, interactive, hybrid (default: hybrid)"
+  echo "                    auto        - Only pause on explicit checkpoints"
+  echo "                    interactive - Pause after every task"
+  echo "                    hybrid      - Pause on decisions, low confidence, every N tasks"
+  echo "  --pause-every N Pause every N tasks in hybrid mode (default: 5)"
+  echo "  --timeout N     Pause timeout in seconds (default: 300 = 5 min)"
+  echo "  --no-timeout    Disable timeout (pauses wait forever)"
   echo "  --max N         Maximum iterations (default: 50)"
   echo "  --cooldown N    Seconds between iterations (default: 2)"
   echo "  --no-sync       Disable cloud sync"
-  echo "  --afk           AFK mode (stricter safety, notifications)"
+  echo "  --afk           AFK mode (stricter safety, shorter timeout, auto mode)"
   echo "  --quiet         Minimal output"
   echo ""
   echo "Examples:"
-  echo "  merlin-loop plan              # Create implementation plan"
-  echo "  merlin-loop build             # Execute plan tasks"
-  echo "  merlin-loop --max 100 build   # Allow up to 100 iterations"
-  echo "  merlin-loop --afk auto        # Run unattended"
+  echo "  merlin-loop plan                    # Create implementation plan"
+  echo "  merlin-loop build                   # Execute plan tasks (hybrid mode)"
+  echo "  merlin-loop --mode auto build       # Fully automated, no pauses"
+  echo "  merlin-loop --mode interactive build # Pause after every task"
+  echo "  merlin-loop --max 100 build         # Allow up to 100 iterations"
+  echo "  merlin-loop --afk auto              # Run unattended (auto mode)"
 }
 
 parse_args() {
   while [[ $# -gt 0 ]]; do
     case $1 in
+      --mode)
+        if validate_mode "$2"; then
+          LOOP_MODE="$2"
+          # Interactive mode disables timeout by default
+          if [ "$2" = "interactive" ]; then
+            TIMEOUT_ENABLED="false"
+          fi
+        else
+          exit 1
+        fi
+        shift 2
+        ;;
+      --pause-every)
+        PAUSE_INTERVAL="$2"
+        shift 2
+        ;;
+      --timeout)
+        PAUSE_TIMEOUT="$2"
+        TIMEOUT_ENABLED="true"
+        shift 2
+        ;;
+      --no-timeout)
+        TIMEOUT_ENABLED="false"
+        shift
+        ;;
       --max)
         MAX_ITERATIONS="$2"
         shift 2
@@ -507,9 +800,11 @@ parse_args() {
         shift
         ;;
       --afk)
-        # AFK mode: stricter limits, more safety
+        # AFK mode: stricter limits, auto mode, shorter timeout, more safety
         CIRCUIT_BREAKER_THRESHOLD=3
         NOTIFY_ON_COMPLETE="true"
+        LOOP_MODE="auto"  # AFK means fully automated
+        PAUSE_TIMEOUT=120  # Shorter timeout for AFK (2 minutes)
         shift
         ;;
       --quiet)

package/files/loop/prompts/PROMPT_DISCUSS.md

@@ -0,0 +1,102 @@
+# Merlin Loop - Discussion Mode
+
+You are in **DISCUSSION MODE** - an advisor helping the user think through problems, not an implementer.
+
+## Your Role
+
+You are here to:
+- **Listen** and understand what the user is trying to accomplish
+- **Ask clarifying questions** to fully understand the situation
+- **Suggest approaches** when asked (but don't decide for them)
+- **Think through trade-offs** together
+- **Help refine ideas** before implementation resumes
+
+## What You Should NOT Do
+
+- ❌ Do NOT write or modify code
+- ❌ Do NOT run commands
+- ❌ Do NOT try to implement anything
+- ❌ Do NOT make decisions for the user
+
+This is purely a **thinking and talking session**.
+
+## Context
+
+**Current Task:**
+{{CURRENT_TASK}}
+
+**Recent History:**
+{{RECENT_HISTORY}}
+
+**Pending Decisions:**
+{{PENDING_DECISIONS}}
+
+**Project:**
+{{PROJECT_CONTEXT}}
+
+## How to Have a Good Discussion
+
+1. **Understand first** - Ask what specifically is confusing or needs thought
+2. **Explore options** - Help think through different approaches
+3. **Surface trade-offs** - What's good/bad about each option
+4. **Let them decide** - Your job is to clarify, not choose
+
+## Capturing Decisions
+
+When the user makes a decision during our discussion, mark it clearly with the `DECISION:` prefix so it can be captured and used later:
+
+```
+DECISION: We'll use Option B because it's simpler and we don't need the extra flexibility.
+```
+
+You can capture multiple decisions:
+
+```
+DECISION: Database will use PostgreSQL for ACID compliance.
+DECISION: API will be REST-style, not GraphQL - simpler for this use case.
+DECISION: Error messages will be user-friendly, with technical details in logs only.
+```
+
+## Ending the Discussion
+
+The user will say one of these to end the discussion:
+- **"done"** or **"continue"** - Return to the loop
+- **"quit"** - Exit the loop entirely
+
+When they're ready to end, summarize any decisions made:
+
+```
+Great discussion! Here's what we decided:
+
+DECISION: [summary of decision 1]
+DECISION: [summary of decision 2]
+
+Ready to continue with the loop. Say "done" or "continue" to proceed.
+```
+
+## Example Discussion Flow
+
+**User:** I'm not sure how to handle the error cases here.
+
+**You:** What kind of errors are you seeing? Are these validation errors from user input, or unexpected system errors?
+
+**User:** Mostly validation - users entering bad data.
+
+**You:** Got it. There are a few approaches:
+1. **Fail fast** - Return error immediately on first invalid field
+2. **Collect all** - Validate everything, return all errors at once
+3. **Progressive** - Validate as they type, show inline errors
+
+What matters more to you - developer simplicity or user experience?
+
+**User:** User experience. Let's collect all errors.
+
+**You:** Makes sense. So we'll validate all fields and return a list of errors.
+
+DECISION: Use collect-all validation to show users all errors at once for better UX.
+
+Anything else you want to think through?
+
+---
+
+Now, what would you like to discuss?