This guide helps you diagnose and fix common issues when using AIA.

# Check AIA version and configuration
aia --version
aia --config

# Enable debug mode for detailed output
aia --debug --verbose my_prompt

# List available models
aia --available_models

# Test fuzzy search
aia --fuzzy

Symptoms:

• Error: "Prompt not found"
• AIA can't locate your prompt file

Solutions:

1. Check prompt file exists:

   ls ~/.prompts/my_prompt.txt
   ls $AIA_PROMPTS_DIR/my_prompt.txt

2. Verify prompts directory:

   echo $AIA_PROMPTS_DIR
   # Should show your prompts directory, defaults to ~/.prompts

3. Use fuzzy search to find prompts:

   aia --fuzzy
   # This opens fzf to search and select prompts interactively

4. Check file permissions:

   ls -la ~/.prompts/
   # Files should be readable (at least 644 permissions)

5. Create the prompt file:

   echo "Your prompt content here" > ~/.prompts/my_prompt.txt

Symptoms:

• "Model not available" error
• Invalid model name errors
• API authentication failures

Solutions:

1. Check available models:

   aia --available_models

2. Verify model name spelling:

   # ✅ Correct model names
   aia --model gpt-4o-mini my_prompt
   aia --model gpt-4o my_prompt
   aia --model gpt-4 my_prompt
   
   # ❌ Common mistakes
   aia --model gpt4 my_prompt      # Missing hyphens
   aia --model gpt-4-mini my_prompt # Wrong name

3. Check API credentials:

   # Ensure your API key is set
   echo $OPENAI_API_KEY
   # Should show your API key (partially masked)

4. Test with default model:

   # Try with the default model first
   aia my_prompt

Symptoms:

• Shell commands in prompts not executing
• Environment variables not expanding
• $(command) patterns not working

Solutions:

1. Test shell patterns separately:

   # Test environment variables
   echo "Home: $HOME"
   echo "User: $USER"
   
   # Test command substitution
   echo "Date: $(date)"
   echo "Directory: $(pwd)"

2. Check shell option is enabled:

   # Shell integration should be enabled by default
   aia --config | grep shell

3. Verify shell command syntax:

   # In prompt files, use:
   Current directory: $(pwd)
   Available files: $(ls -la)

4. Test with simple commands first:

   # Create a test prompt
   echo "Current time: \$(date)" > ~/.prompts/test_shell.txt
   aia test_shell

Symptoms:

• Configuration not loading
• Environment variables ignored
• Conflicting settings

Diagnostic Steps:

1. Check configuration hierarchy:

   aia --debug --config
   # Shows configuration loading process and values

2. Verify configuration file syntax:

   # ~/.aia/config.yml should be valid YAML
   model: gpt-4o-mini
   temperature: 0.7
   prompts_dir: ~/my-prompts

3. Test configuration precedence:

   # Command line should override environment variables
   AIA_MODEL=gpt-4 aia --model gpt-4o-mini --config
   # Should show gpt-4o-mini as the active model

Symptoms:

• "command not found: aia"
• "fzf not found" errors
• Ruby version errors

Solutions:

1. Check Ruby version:

   ruby --version
   # Should be >= 3.2.0

2. Verify AIA installation:

   gem list aia
   which aia

3. Install missing dependencies:

   # Install fzf if missing
   brew install fzf          # macOS
   sudo apt install fzf      # Ubuntu/Debian
   sudo pacman -S fzf        # Arch Linux

4. Reinstall AIA if necessary:

   gem uninstall aia
   gem install aia

Symptoms:

• ERB code not executing
• Template syntax errors
• Ruby code errors in prompts

Solutions:

1. Check ERB is enabled:

   aia --config | grep erb
   # Should show erb: true

2. Test simple ERB:

   echo "Current time: <%= Time.now %>" > ~/.prompts/test_erb.txt
   aia test_erb

3. Debug ERB syntax:

   <%# This is a comment %>
   <% name = "World" %>
   Hello, <%= name %>!

4. Common ERB patterns:

   <%# Conditional content %>
   <% if ENV['USER'] == 'admin' %>
   You have admin privileges.
   <% end %>
   
   <%# Loops %>
   <% [1,2,3].each do |num| %>
   Number: <%= num %>
   <% end %>

Symptoms:

• Chat not starting
• Responses not generating
• Chat history issues

Solutions:

1. Test basic chat:

   aia --chat
   # Should start interactive session

2. Check with different model:

   aia --chat --model gpt-4o-mini

3. Clear chat context:

   # In chat session, use:
   //clear

4. Enable verbose mode:

   aia --chat --verbose

Symptoms:

• Slow responses
• Timeouts
• Large prompt processing issues

Solutions:

1. Use faster models:

   aia --model gpt-4o-mini my_prompt  # Faster than gpt-4

2. Reduce token limits:

   aia --max_tokens 1000 my_prompt

3. Optimize temperature:

   aia --temperature 0.1 my_prompt    # Lower = faster

4. Break large prompts into pipelines:

   aia part1 --pipeline part2,part3

Symptoms:

• Tools not loading
• Tool execution failures
• Permission errors with tools

Solutions:

1. Test tool loading:

   aia --chat --tools shared --debug

2. Check tool file permissions:

   ls -la ~/my-tools/
   # Tool files should be readable

3. Validate tool syntax:

   # Ensure tools inherit from RubyLLM::Tool
   class MyTool < RubyLLM::Tool
     description "Tool description"
     # ...
   end

4. Use tool filtering:

   aia --chat --tools shared --allowed_tools read_file,write_file

Symptoms:

• Executable prompt content not appearing in LLM input
• Content from executable file seems to be ignored
• Only base prompt content is processed

Solutions:

Problem Description: When using an executable prompt file that references a base prompt containing a __END__ marker, the executable file's content gets filtered out because it appears after the __END__ line in the combined prompt.

Example of the Problem:

Base prompt file (~/.prompts/system.txt):

You are a helpful assistant with system-level access.

Follow these guidelines:
- Be thorough and accurate
- Provide detailed explanations

__END__
This is a comment block that won't be processed.
Additional documentation goes here.

Executable prompt file (my_prompt):

#!/usr/bin/env aia run system --exec --no-out_file
Analyze the current system status and provide recommendations.

When executed, the content "Analyze the current system status..." appears AFTER the __END__ marker in memory, so it gets filtered out as a comment.

Solution:

Replace the __END__ marker with HTML-style comments in your base prompt:

You are a helpful assistant with system-level access.

Follow these guidelines:
- Be thorough and accurate  
- Provide detailed explanations

<!--
This is a comment block that won't be processed.
Additional documentation goes here.
-->

Alternative Solutions:

1. Remove __END__ entirely if comments aren't needed:

   You are a helpful assistant with system-level access.
   
   Follow these guidelines:
   - Be thorough and accurate
   - Provide detailed explanations
   

2. Use a different base prompt without __END__ markers for executable prompts.

3. Move comments to the top of the base prompt file:

   <!--
   Documentation and comments at the top
   -->
   
   You are a helpful assistant with system-level access.
   

Problem: Content with environment variables, shell commands, or directives not being processed.

Solution: Ensure the --exec option is used in the shebang line:

# ❌ Wrong - dynamic content won't be processed
#!/usr/bin/env aia run system --no-out_file

# ✅ Correct - dynamic content will be processed  
#!/usr/bin/env aia run system --exec --no-out_file

Problem: Executable prompt file can't be executed.

Solutions:

1. Make file executable:

   chmod +x my_prompt

2. Check file permissions:

   ls -la my_prompt
   # Should show execute permissions (x)

3. Test execution directly:

   ./my_prompt
   # Should work if permissions are correct

Problem: Shebang line not working or command not found.

Solutions:

1. Verify AIA location:

   which aia
   # Use the full path if needed: #!/usr/local/bin/aia

2. Test shebang line syntax:

   # Simple test
   head -1 my_prompt
   # Should show: #!/usr/bin/env aia run [options]

3. Common shebang patterns:

   # Basic executable prompt
   #!/usr/bin/env aia run --no-out_file
   
   # With dynamic content processing
   #!/usr/bin/env aia run --exec --no-out_file
   
   # With specific base prompt
   #!/usr/bin/env aia run system --exec --no-out_file
   
   # With tools
   #!/usr/bin/env aia run --exec --no-out_file --tools shared

Enable comprehensive debugging:

# Full debug output
aia --debug --verbose my_prompt

# Debug specific components
AIA_DEBUG=true aia my_prompt

# Check configuration loading
aia --debug --config

Debug output includes:

• Configuration loading process
• Prompt file processing
• Directive execution
• API communication
• Error stack traces

Check AIA's log file for issues:

# View recent log entries
tail -50 ~/.prompts/_prompts.log

# Search for errors
grep -i error ~/.prompts/_prompts.log

# Monitor log in real-time
tail -f ~/.prompts/_prompts.log

Create a diagnostic script to check your setup:

#!/bin/bash
# aia_diagnostic.sh

echo "=== AIA Diagnostic Report ==="
echo
echo "Ruby version:"
ruby --version
echo
echo "AIA version:"
aia --version 2>/dev/null || echo "AIA not found"
echo
echo "Required tools:"
which fzf >/dev/null && echo "✅ fzf found" || echo "❌ fzf missing"
echo
echo "Environment variables:"
echo "AIA_PROMPTS_DIR: ${AIA_PROMPTS_DIR:-~/.prompts (default)}"
echo "AIA_MODEL: ${AIA_MODEL:-gpt-4o-mini (default)}"
echo "AIA_VERBOSE: ${AIA_VERBOSE:-false (default)}"
echo
echo "Prompts directory:"
ls -la "${AIA_PROMPTS_DIR:-$HOME/.prompts}" 2>/dev/null || echo "Prompts directory not found"
echo
echo "Configuration file:"
ls -la ~/.aia/config.yml 2>/dev/null || echo "No config file found"

• GitHub Issues: Report bugs and issues
• Wiki: AIA Wiki for documentation
• Examples: Check the examples/ directory in the repository

When reporting issues, include:

1. AIA version: aia --version
2. Ruby version: ruby --version
3. Operating system: uname -a
4. Steps to reproduce: Exact commands and files used
5. Expected vs actual behavior
6. Debug output: aia --debug --verbose
7. Configuration: aia --config (remove sensitive data)

## Bug Report

**AIA Version:** 0.x.x
**Ruby Version:** 3.2.x
**OS:** macOS/Linux/Windows

**Steps to Reproduce:**
1. Create prompt file: `echo "test" > ~/.prompts/test.txt`
2. Run command: `aia test`
3. Error occurs

**Expected Behavior:**
Should process prompt and generate response

**Actual Behavior:**
Error: "Prompt not found"

**Debug Output:**

[paste debug output here]

**Additional Context:**
Any other relevant information

# Update AIA regularly
gem update aia

# Clean up old log entries
> ~/.prompts/_prompts.log

# Check for broken prompts
find ~/.prompts -name "*.txt" -exec aia --dry-run {} \;

1. Test prompts in isolation before using in workflows
2. Use version control for important prompts
3. Keep backups of your prompts directory
4. Monitor resource usage with complex prompts
5. Validate shell commands before including in prompts

By following this troubleshooting guide, you should be able to diagnose and resolve most common AIA issues. If problems persist, don't hesitate to seek help from the community or file a bug report.