ralph-claude-code/docs/archive/2025-10-milestones/USE_CASES.md

Ralph Use Cases

Author: Based on Alistair Cockburn's use case methodology Date: 2025-10-01 Purpose: Define actors, goals, and scenarios for Ralph autonomous development system

---

System Overview

System Name: Ralph - Autonomous AI Development Loop System Goal: Complete software project implementation with minimal human intervention and token waste Primary Actor: Ralph (bash script orchestrating Claude Code) Supporting Actors: Claude Code (AI development engine), Human Developer (initiator and reviewer)

---

Actor Catalog

Primary Actor: Ralph (Autonomous Agent)

Type: System Goal: Execute development loops until project completion or circuit breaker opens Capabilities:

• Execute Claude Code with PROMPT.md instructions
• Analyze Claude Code responses for completion signals
• Track file changes and progress
• Manage rate limits (100 calls/hour)
• Detect stagnation via circuit breaker
• Gracefully exit when work is complete

Constraints:

• Cannot modify project requirements
• Must respect API rate limits
• Cannot override circuit breaker when open
• Requires valid PROMPT.md and fix_plan.md

---

Supporting Actor: Claude Code

Type: AI System Goal: Implement features, fix bugs, run tests per PROMPT.md instructions Capabilities:

• Read/write/edit files
• Execute bash commands
• Run tests and analyze results
• Search codebase
• Output structured status reports

Constraints:

• 5-hour daily API limit
• Token context limits
• Cannot access external network (except via approved tools)
• Must follow PROMPT.md instructions

---

Supporting Actor: Human Developer

Type: Human Goal: Initiate Ralph, review results, intervene when needed Capabilities:

• Create PROMPT.md and fix_plan.md
• Start/stop Ralph execution
• Reset circuit breaker
• Review code changes
• Provide clarifications when blocked

Constraints:

• Not present during autonomous loop execution
• Cannot modify files while Ralph is running
• Must review changes before merging

---

Use Case Hierarchy

System Goal: Complete Project Implementation

Sub-Goals:

1. Execute development loops (UC-1)
2. Detect completion conditions (UC-2)
3. Prevent resource waste (UC-3)
4. Handle error conditions (UC-4)
5. Provide observability (UC-5)

---

UC-1: Execute Development Loop

Primary Actor: Ralph Stakeholders: Human Developer (wants progress), Claude Code (executor) Preconditions:

• PROMPT.md exists and is valid
• fix_plan.md exists with at least one task
• Claude Code CLI is installed and accessible
• git repository is initialized

Success Guarantee (Postcondition):

• One development task completed
• Files modified and committed (if changes made)
• Status tracked in logs and status.json
• Circuit breaker state updated
• Exit signals analyzed and recorded

Main Success Scenario:

1. Ralph reads PROMPT.md
2. Ralph checks circuit breaker state (must be CLOSED or HALF_OPEN)
3. Ralph verifies rate limit allows execution
4. Ralph executes Claude Code with PROMPT.md
5. Claude Code reads fix_plan.md and selects task
6. Claude Code implements task (files modified)
7. Claude Code runs relevant tests
8. Claude Code outputs RALPH_STATUS block
9. Ralph analyzes Claude's response (analyze_response)
10. Ralph updates .exit_signals file (update_exit_signals)
11. Ralph records loop result in circuit breaker (record_loop_result)
12. Ralph increments call counter
13. Ralph logs completion to status.json and logs/
14. Ralph continues to next loop (if no exit condition)

Extensions (Alternative Flows):

2a. Circuit breaker is OPEN:

• 2a1. Ralph displays circuit breaker status
• 2a2. Ralph shows user guidance (check logs, reset, etc.)
• 2a3. Ralph exits with exit code 1
• USE CASE ENDS

3a. Rate limit exceeded:

• 3a1. Ralph calculates time until next hour reset
• 3a2. Ralph displays countdown timer
• 3a3. Ralph waits for reset
• 3a4. Ralph continues at step 4

3b. API 5-hour limit reached:

• 3b1. Ralph detects "rate limit" error in Claude output
• 3b2. Ralph prompts user: retry or exit?
• 3b3a. User chooses retry: wait 5 minutes, go to step 4
• 3b3b. User chooses exit: Ralph exits gracefully
• USE CASE ENDS

4a. Claude Code execution fails:

• 4a1. Ralph logs error to logs/ralph_error.log
• 4a2. Ralph updates status.json with "failed" status
• 4a3. Ralph continues to next loop (retry)
• 4a4. If 5 consecutive failures: circuit breaker opens
• Continue at step 2

9a. Response analysis detects EXIT_SIGNAL=true:

• 9a1. Ralph logs successful completion
• 9a2. Ralph updates status.json with "complete" status
• 9a3. Ralph displays completion summary
• 9a4. Ralph exits with exit code 0
• USE CASE ENDS

11a. Circuit breaker opens (no progress detected):

• 11a1. Ralph logs circuit breaker opening
• 11a2. Ralph updates status.json with "circuit_open" status
• 11a3. Ralph displays guidance to user
• 11a4. Ralph exits with exit code 1
• USE CASE ENDS

Frequency: Occurs in loop until completion or exit condition Performance: Each loop should complete in < 5 minutes under normal conditions

---

UC-2: Detect Project Completion

Primary Actor: Ralph (via response_analyzer.sh) Stakeholders: Human Developer (wants reliable exit), Claude Code (signals completion) Preconditions:

• Development loop has executed (UC-1)
• Claude Code has produced output

Success Guarantee:

• Completion status accurately determined
• .exit_signals file updated with decision
• Confidence score calculated (0-100+)
• EXIT_SIGNAL set correctly (true/false)

Main Success Scenario:

1. Ralph reads Claude Code output file
2. Ralph checks for structured RALPH_STATUS block
3. Ralph finds STATUS: COMPLETE and EXIT_SIGNAL: true
4. Ralph sets confidence score to 100
5. Ralph sets exit_signal to true in .response_analysis
6. Ralph updates .exit_signals with done_signals array
7. Ralph triggers graceful exit in next loop check

Extensions:

2a. No structured output found:

• 2a1. Ralph searches for natural language completion keywords
• 2a2. If found: add +10 to confidence score
• 2a3. Ralph checks for "nothing to do" patterns
• 2a4. If found: add +15 to confidence score, set exit_signal=true
• Continue at step 6

3a. STATUS shows IN_PROGRESS:

• 3a1. Ralph checks WORK_TYPE field
• 3a2. If WORK_TYPE=TESTING for 3rd consecutive loop: mark as test_only
• 3a3. If FILES_MODIFIED=0 for 3rd consecutive loop: circuit breaker opens
• 3a4. Set exit_signal to false
• Continue at step 6

3b. STATUS shows BLOCKED:

• 3b1. Ralph increments blocked_loops counter
• 3b2. If blocked_loops >= 3: recommend human intervention
• 3b3. Set exit_signal to false
• Continue at step 6

6a. Confidence score >= 40:

• 6a1. Even without explicit EXIT_SIGNAL, set exit_signal=true
• 6a2. Log high confidence completion detection
• Continue at step 7

Frequency: After every development loop Performance: Analysis should complete in < 1 second

---

UC-3: Prevent Resource Waste (Circuit Breaker)

Primary Actor: Ralph (via circuit_breaker.sh) Stakeholders: Human Developer (wants to avoid token waste) Preconditions:

• Development loops are executing
• Circuit breaker is initialized

Success Guarantee:

• Runaway loops detected and halted
• Token waste minimized (< 1K wasted tokens)
• Clear user guidance provided on halt
• Circuit breaker state persisted across restarts

Main Success Scenario:

1. Ralph initializes circuit breaker to CLOSED state
2. After each loop, Ralph calls record_loop_result()
3. Ralph counts files_changed from git diff
4. Ralph detects has_errors from Claude output
5. Ralph calculates output_length
6. Circuit breaker updates consecutive_no_progress counter
7. consecutive_no_progress is 0 (progress detected)
8. Circuit breaker stays CLOSED
9. Ralph continues to next loop

Extensions:

6a. No files changed (consecutive_no_progress increments):

• 6a1. consecutive_no_progress = 1
• 6a2. Circuit breaker stays CLOSED
• Continue at step 9

6b. No files changed for 2nd consecutive loop:

• 6b1. consecutive_no_progress = 2
• 6b2. Circuit breaker transitions to HALF_OPEN
• 6b3. Ralph logs "monitoring mode" warning
• Continue at step 9

6c. No files changed for 3rd consecutive loop:

• 6c1. consecutive_no_progress = 3
• 6c2. Circuit breaker transitions to OPEN
• 6c3. Ralph displays halt message with guidance
• 6c4. Ralph exits with exit code 1
• USE CASE ENDS

6d. Same error detected for 5th consecutive loop:

• 6d1. consecutive_same_error = 5
• 6d2. Circuit breaker transitions to OPEN
• 6d3. Reason: "Same error repeated in 5 consecutive loops"
• Continue at step 6c3

7a. Files changed detected (recovery):

• 7a1. consecutive_no_progress resets to 0
• 7a2. If circuit was HALF_OPEN: transition to CLOSED
• 7a3. Ralph logs "circuit recovered"
• Continue at step 9

Frequency: After every development loop Performance: Circuit breaker check < 100ms

---

UC-4: Handle API Rate Limits

Primary Actor: Ralph Stakeholders: Human Developer (wants uninterrupted execution) Preconditions:

• Ralph is executing development loops
• Call tracking is initialized

Success Guarantee:

• API rate limits respected
• Call counter accurately tracked
• Hourly reset handled automatically
• User informed of wait times

Main Success Scenario:

1. Ralph checks current hour (YYYYMMDDHH format)
2. Ralph reads .last_reset timestamp
3. Current hour matches last_reset (same hour)
4. Ralph reads .call_count
5. call_count is 45 (< 100 limit)
6. Ralph allows execution
7. Ralph increments call_count to 46
8. Ralph writes updated count to .call_count
9. Execution proceeds

Extensions:

3a. New hour detected (hour changed):

• 3a1. Ralph resets call_count to 0
• 3a2. Ralph writes current hour to .last_reset
• 3a3. Ralph logs "call counter reset for new hour"
• Continue at step 5

5a. call_count equals or exceeds limit (100):

• 5a1. Ralph calculates seconds until next hour
• 5a2. Ralph displays countdown: "Rate limit reached. Waiting HH:MM:SS..."
• 5a3. Ralph sleeps for calculated duration
• 5a4. Ralph resets counter (go to step 3a1)
• Continue at step 6

5b. Claude returns API rate limit error:

• 5b1. Ralph detects "rate_limit_error" in output
• 5b2. Ralph prompts: "API 5-hour limit reached. Retry? (y/n)"
• 5b3a. User enters 'y': Ralph waits 5 minutes, retries
• 5b3b. User enters 'n': Ralph exits gracefully
• USE CASE ENDS

Frequency: Before every Claude Code execution Performance: Rate limit check < 50ms

---

UC-5: Provide Loop Monitoring

Primary Actor: ralph-monitor.sh Stakeholders: Human Developer (wants real-time visibility) Preconditions:

• Ralph is running (ralph_loop.sh)
• ralph-monitor started in separate terminal

Success Guarantee:

• Real-time status displayed and updated
• Loop count, rate limits, and progress visible
• Circuit breaker state shown
• Exit signals tracked

Main Success Scenario:

1. User starts ralph-monitor.sh in separate terminal
2. Monitor reads status.json every 2 seconds
3. Monitor displays loop count, status, timestamp
4. Monitor reads .call_count and shows "Calls: 45/100"
5. Monitor reads .circuit_breaker_state and shows state
6. Monitor reads .exit_signals and shows signal counts
7. Monitor detects status.json update
8. Monitor refreshes display with new data
9. Loop continues (go to step 2)

Extensions:

3a. status.json doesn't exist yet:

• 3a1. Monitor displays "Waiting for Ralph to start..."
• 3a2. Monitor sleeps 2 seconds
• Continue at step 2

5a. Circuit breaker is OPEN:

• 5a1. Monitor displays status in RED
• 5a2. Monitor shows reason for circuit opening
• 5a3. Monitor displays "Execution halted" message
• Continue at step 7

7a. Ralph has exited:

• 7a1. Monitor detects final status
• 7a2. Monitor displays completion summary
• 7a3. Monitor shows total loops, duration, exit reason
• 7a4. Monitor exits
• USE CASE ENDS

Frequency: Continuous until Ralph exits Performance: Update latency < 2 seconds

---

UC-6: Reset Circuit Breaker (Manual Intervention)

Primary Actor: Human Developer Stakeholders: Ralph (needs manual reset to continue) Preconditions:

• Circuit breaker is OPEN
• Ralph has halted execution
• User has reviewed logs and identified issue

Success Guarantee:

• Circuit breaker reset to CLOSED state
• Counters reset to 0
• Ralph can resume execution
• Reset reason logged

Main Success Scenario:

1. User identifies circuit breaker opened (from ralph-monitor or logs)
2. User reviews logs/ralph.log to understand cause
3. User fixes underlying issue (updates fix_plan.md, fixes error, etc.)
4. User runs: ralph --reset-circuit
5. Ralph loads circuit_breaker.sh functions
6. Ralph calls reset_circuit_breaker("Manual reset by user")
7. Ralph sets state to CLOSED in .circuit_breaker_state
8. Ralph resets all counters to 0
9. Ralph logs "Circuit breaker reset to CLOSED state"
10. Ralph displays success message
11. User can now restart Ralph execution

Extensions:

2a. User cannot determine cause from logs:

• 2a1. User runs: ralph --status for additional info
• 2a2. User checks .circuit_breaker_history for state transitions
• 2a3. User reviews recent Claude output files
• Continue at step 3

3a. Issue is in PROMPT.md or specs/:

• 3a1. User edits PROMPT.md to clarify requirements
• 3a2. User updates specs/ with missing information
• 3a3. User commits changes
• Continue at step 4

3b. Issue is configuration or environment:

• 3b1. User installs missing dependencies
• 3b2. User fixes environment variables
• 3b3. User verifies configuration
• Continue at step 4

Frequency: As needed when circuit breaker opens Performance: Reset is instantaneous

---

Goal Hierarchy

SYSTEM GOAL: Complete project implementation with minimal token waste
├─ SUB-GOAL 1: Execute development loops (UC-1)
│  ├─ Success: Files changed, tests pass, tasks completed
│  └─ Failure: No files changed, tests fail, no progress
│
├─ SUB-GOAL 2: Detect when no more progress is possible (UC-2)
│  ├─ Success: Exit gracefully with completion summary
│  └─ Failure: Continue looping when work is done
│
├─ SUB-GOAL 3: Prevent resource waste (UC-3)
│  ├─ Success: Halt execution when stagnant
│  └─ Failure: Burn tokens in infinite loops
│
├─ SUB-GOAL 4: Respect API limits (UC-4)
│  ├─ Success: Wait for reset, continue seamlessly
│  └─ Failure: Exceed limits, API errors
│
└─ SUB-GOAL 5: Provide visibility (UC-5)
   ├─ Success: User has real-time status
   └─ Failure: Black box, no feedback

---

Success Metrics

Use Case	Success Criteria	Target
UC-1	Loop completion rate	> 95%
UC-1	Average loop duration	< 5 minutes
UC-2	Completion detection accuracy	> 90%
UC-2	False positive rate	< 5%
UC-3	Circuit breaker trip time	< 3 loops
UC-3	Token waste on stagnation	< 1,000 tokens
UC-4	Rate limit compliance	100%
UC-4	Wait time on limit	Minimal
UC-5	Monitor update latency	< 2 seconds
UC-6	Manual reset success	100%

---

Non-Functional Requirements

Reliability

• Availability: 99%+ when network and API available
• Fault Tolerance: Graceful handling of Claude API errors
• Data Integrity: No data loss on unexpected termination

Performance

• Response Time: Status checks < 100ms
• Throughput: Support continuous operation for days
• Scalability: Handle projects with 100+ loops

Usability

• Learnability: New users understand system in < 30 minutes
• Error Messages: Clear, actionable guidance on failures
• Documentation: Complete use cases and examples

Security

• Authentication: Respects Claude API authentication
• Authorization: Operates only on authorized files
• Data Privacy: No sensitive data logged

---

Glossary

Term	Definition
Circuit Breaker	Pattern that prevents runaway loops by detecting stagnation
Exit Signal	Indicator that Claude has completed all work
Loop	One iteration of Ralph executing Claude Code
Rate Limit	Maximum API calls allowed per hour (100)
Response Analyzer	Component that parses Claude output for signals
Stagnation	Condition where no progress is being made (no file changes)
Test-Only Loop	Loop where only tests run, no implementation work

---

Document Version: 1.0 Last Updated: 2025-10-01 Author: Based on Alistair Cockburn's use case methodology Status: Phase 2 Documentation - Complete