Phase 2: Requirements, testing, and documentation enhancements
Implements all Phase 2 high-priority recommendations from expert panel: **1. Requirements Improvement** (Karl Wiegers, Gojko Adzic) - Enhanced templates/PROMPT.md with 6 concrete Given/When/Then scenarios - Specification by Example format for all exit conditions - Clear expectations for each scenario type: * Successful completion * Test-only loops * Stuck on errors * No work remaining * Making progress * Blocked on dependencies **2. Use Case Documentation** (Alistair Cockburn) - Created comprehensive USE_CASES.md (600+ lines) - Defined 6 primary use cases with full Cockburn format: * UC-1: Execute Development Loop * UC-2: Detect Project Completion * UC-3: Prevent Resource Waste * UC-4: Handle API Rate Limits * UC-5: Provide Loop Monitoring * UC-6: Reset Circuit Breaker - Includes actors, goals, success scenarios, extensions, edge cases - Clear goal hierarchy and success metrics **3. Enhanced Test Coverage** (Lisa Crispin, Janet Gregory) - Added tests/integration/test_edge_cases.bats (20 new tests) - Edge cases: empty files, large files, corrupted JSON, unicode - Boundary conditions: exact thresholds, overflow scenarios - Error conditions: missing git, malformed data, rapid transitions - All 40 integration tests passing (100% success rate) **4. Circuit Breaker Robustness** - Enhanced init_circuit_breaker() with corruption detection - Auto-recovery from corrupted state/history files - Validates JSON before use, recreates if invalid **5. Specification Workshop Guide** - Created SPECIFICATION_WORKSHOP.md - Three Amigos methodology with templates - Includes complete example workshop - Best practices and red flags - Quick 15-minute template for small features **Test Results**: 40/40 integration tests passing **Documentation Added**: 1,200+ lines (USE_CASES.md, SPECIFICATION_WORKSHOP.md) **Coverage Improvement**: Edge cases and error conditions fully tested 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
frankbria
parent
03abd89fc8
commit
3ae67f66ac
6 changed files with 1569 additions and 1 deletions
523
USE_CASES.md
Normal file
523
USE_CASES.md
Normal file
|
|
@ -0,0 +1,523 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue