From 738e91ad54d96a42192dcf2029d7eab372fa7402 Mon Sep 17 00:00:00 2001
From: frankbria <frank.bria@gmail.com>
Date: Wed, 27 Aug 2025 13:38:11 -0700
Subject: [PATCH] Fix silent exit bug and improve error messages in ralph
 command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🐛 Bug Fix: Silent Exit Issue
- Ralph was silently exiting when PROMPT.md not found (no error shown)
- Added comprehensive error handling with helpful guidance
- Now clearly explains when directory is not a Ralph project

🎯 Enhanced User Experience:
- Detects partial Ralph projects vs completely wrong directories
- Provides specific actionable solutions:
  1. ralph-setup my-project (create new)
  2. ralph-import requirements.md (import existing)
  3. Navigate to existing Ralph project
  4. Create PROMPT.md manually
- Updated help text with "IMPORTANT" note about project directories
- Added example workflow in help documentation

🔧 Technical Improvements:
- Better error detection logic
- Informative messages instead of silent failures
- Maintains proper exit codes for scripting
- Clear guidance for different scenarios

This resolves the confusing behavior where ralph would start logging
but then silently exit without explanation when run outside a Ralph project.
---
 ralph_loop.sh | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/ralph_loop.sh b/ralph_loop.sh
index bf9efc0..63828b9 100755
--- a/ralph_loop.sh
+++ b/ralph_loop.sh
@@ -312,9 +312,27 @@ main() {
     log_status "INFO" "Max calls per hour: $MAX_CALLS_PER_HOUR"
     log_status "INFO" "Logs: $LOG_DIR/ | Docs: $DOCS_DIR/ | Status: $STATUS_FILE"
     
-    # Check if prompt file exists
+    # Check if this is a Ralph project directory
     if [[ ! -f "$PROMPT_FILE" ]]; then
         log_status "ERROR" "Prompt file '$PROMPT_FILE' not found!"
+        echo ""
+        
+        # Check if this looks like a partial Ralph project
+        if [[ -f "@fix_plan.md" ]] || [[ -d "specs" ]] || [[ -f "@AGENT.md" ]]; then
+            echo "This appears to be a Ralph project but is missing PROMPT.md."
+            echo "You may need to create or restore the PROMPT.md file."
+        else
+            echo "This directory is not a Ralph project."
+        fi
+        
+        echo ""
+        echo "To fix this:"
+        echo "  1. Create a new project: ralph-setup my-project"
+        echo "  2. Import existing requirements: ralph-import requirements.md"
+        echo "  3. Navigate to an existing Ralph project directory"
+        echo "  4. Or create PROMPT.md manually in this directory"
+        echo ""
+        echo "Ralph projects should contain: PROMPT.md, @fix_plan.md, specs/, src/, etc."
         exit 1
     fi
     
@@ -371,6 +389,9 @@ Ralph Loop for Claude Code
 
 Usage: $0 [OPTIONS]
 
+IMPORTANT: This command must be run from a Ralph project directory.
+           Use 'ralph-setup project-name' to create a new project first.
+
 Options:
     -h, --help          Show this help message
     -c, --calls NUM     Set max calls per hour (default: $MAX_CALLS_PER_HOUR)
@@ -383,8 +404,14 @@ Files created:
     - $DOCS_DIR/: Generated documentation
     - $STATUS_FILE: Current status (JSON)
 
-Example:
+Example workflow:
+    ralph-setup my-project     # Create project
+    cd my-project             # Enter project directory  
+    $0 --monitor             # Start Ralph with monitoring
+
+Examples:
     $0 --calls 50 --prompt my_prompt.md
+    $0 --monitor             # Start with integrated tmux monitoring
 
 HELPEOF
 }