Troubleshooting

Solutions for common Ralph issues.

Agent Loop Troubleshooting

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Solutions for common Ralph issues.

Common Issues

"Max iterations reached"

Symptom: Loop stops at iteration limit without completing.

Possible Causes: 1. Task too broad 2. Criteria impossible to satisfy 3. Underlying issue preventing progress 4. Each fix creates new problems

Solutions:

1. Check if progress was made:

   /ralph-status the verbose option

If each iteration fixed something, increase limits:

   /ralph-resume the max-iterations option 20

2. Split the task:

   # Instead of
   /ralph "Fix all tests" the completion option "npm test passes"

   # Try
   /ralph "Fix auth tests" the completion option "npm test -- auth"
   /ralph "Fix utils tests" the completion option "npm test -- utils"

3. Verify criteria manually:

   npm test
   # Is it even possible for this to pass?

4. Add more context:

   /ralph "Fix tests - the auth mock needs updating for new API" \
     the completion option "npm test passes"

"Timeout reached"

Symptom: Loop stops due to time limit.

Solutions:

1. Resume with longer timeout:

   /ralph-resume the timeout option 120

2. Check if task is making progress:

   /ralph-status the verbose option

If no progress, the task may need restructuring.

3. Use faster verification:

   # Instead of full test suite
   the completion option "npm test -- --testPathPattern=specific"

"Verification command failed to execute"

Symptom: Can't run the completion criteria command.

Causes: 1. Command doesn't exist 2. Missing dependencies 3. Wrong working directory 4. Syntax error in criteria

Solutions:

1. Test command manually:

   npm test
   # Does this work?

2. Check dependencies:

   npm install

3. Verify path:

   pwd
   ls package.json

4. Fix criteria syntax:

   # Wrong
   the completion option "npm test | grep pass"

   # Right
   the completion option "npm test passes"

"Same error every iteration"

Symptom: No progress between iterations - same failure each time.

Causes: 1. Error not fixable by code changes 2. External dependency issue 3. Criteria misunderstood 4. Wrong files being modified

Solutions:

1. Check the error carefully: Is it actually something code changes can fix?

2. Verify external dependencies:

   # Database running?
   # API accessible?
   # Environment variables set?

3. Provide more specific task:

   /ralph-abort
   /ralph "Fix the specific error: [paste exact error message]" \
     the completion option "npm test passes"

4. Check file scope: Is Ralph modifying the right files? Check git status.

"Progress then regression"

Symptom: Fix one thing, break another. Oscillating.

Causes: 1. Incomplete criteria (only tests, not lint) 2. Hidden dependencies between components 3. Incomplete understanding of codebase

Solutions:

1. Use compound criteria:

   /ralph "Fix all issues" \
     the completion option "npm test passes AND npm run lint passes AND npx tsc --noEmit passes"

2. Add tests for fixed issues: Include test creation in the task so fixes stick.

3. Narrow the scope: Work on one module at a time.

"Can't resume" / "No loop to resume"

Symptom: `/ralph-resume` fails to find a loop.

Causes: 1. State file deleted 2. Loop completed or aborted 3. Wrong directory

Solutions:

1. Check state:

   cat .aiwg/ralph/current-loop.json

2. If state missing, start fresh:

   /ralph "task" the completion option "criteria"

3. Check directory:

   pwd
   ls .aiwg/ralph/

"Git conflicts during iteration"

Symptom: Commit fails due to conflicts.

Solutions:

1. Resolve conflicts manually:

   git status
   # Fix conflicts
   git add .
   git commit -m "resolve conflicts"

2. Resume the loop:

   /ralph-resume

3. Or start fresh on clean branch:

   git checkout -b ralph-fresh
   /ralph "task" the completion option "criteria"

Debugging Techniques

View Full Iteration History

/ralph-status the verbose option

Or manually:

cat .aiwg/ralph/current-loop.json | jq
ls .aiwg/ralph/iterations/
cat .aiwg/ralph/iterations/iteration-1.json

Check Git History

git log the oneline option -10
# Look for "ralph: iteration N" commits

Manual Verification

# Run the verification command yourself
npm test
echo $?  # Should be 0 for success

# Check output for clues
npm test 2>&1 | head -50

Trace Analysis (if aiwg-hooks enabled)

Use AIWG to complete this documented outcome: Trace Analysis (if aiwg-hooks enabled)
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Examine Learnings

cat .aiwg/ralph/current-loop.json | jq '.learnings'
cat .aiwg/ralph/current-loop.json | jq '.iterations[].learnings'

Recovery Procedures

Clean Slate

Delete all Ralph state and start fresh:

rm -rf .aiwg/ralph/
/ralph "task" the completion option "criteria"

Revert All Changes

If Ralph made things worse:

/ralph-abort the revert option

Or manually:

git log the oneline option -20  # Find commit before ralph started
git reset the hard option <commit>

Partial Recovery

Keep some iterations, undo recent:

git log the oneline option -10
git reset the hard option HEAD~3  # Undo last 3 iterations
/ralph-resume

Getting Help

1. Check this troubleshooting guide 2. Review Best Practices 3. Look at Examples for similar tasks 4. Ask in Discord: https://discord.gg/BuAusFMxdA 5. File issue: https://github.com/jmagly/aiwg/issues

When reporting issues, include:

Task description
Completion criteria
Current iteration count
Error message or unexpected behavior
Contents of `.aiwg/ralph/current-loop.json`