ralph-loop-integration

# Ralph-Loop Integration for Cognitive Reasoning **Purpose**: Integrate ralph-loop's persistent iteration mechanism with cognitive reasoning patterns. Ralph provides session persistence through Stop hooks and completion promises, enabling iterative refinement of reasoning until confidence thresholds are genuinely met. ## Core Concept: Ralph-Loop Mechanics ### What Ralph Does Ralph is a Claude Code plugin that provides: 1. **Stop Hook Blocking**: Intercepts session exit and re-feeds the prompt 2. **Completion Promise Gating**: Exit only when `<promise>` tag evaluates to genuinely true 3. **State Persistence**: Maintains iteration context in `.claude/ralph-loop.local.md` 4. **Anti-Gaming Protection**: Promise must be genuinely satisfied, not just claimed ``` ┌─────────────────────────────────────────────────────────┐ │ Ralph-Loop Wrapper │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │ │ │ Iteration 1 │ ──→ │ Iteration 2 │ ──→ │ ... │ │ │ │ (Pattern A) │ │ (Pattern B) │ │ │ │ │ └─────────────┘ └─────────────┘ └──────────┘ │ │ │ │ │ │ │ └───────────────────┴──────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────┐ │ │ │ Stop Hook │ │ │ │ Evaluation │ │ │ └───────┬───────┘ │ │ │ │ │ ┌────────────┼────────────┐ │ │ │ │ │ │ │ ▼ │ ▼ │ │ ┌─────────────┐ │ ┌─────────────┐ │ │ │ Promise │ │ │ Promise │ │ │ │ NOT MET │ │ │ MET │ │ │ │ → Re-loop │ │ │ → Exit │ │ │ └─────────────┘ │ └─────────────┘ │ │ │ │ └───────────────────────────┼─────────────────────────────┘ │ ▼ .claude/ralph-loop.local.md (State persistence) ``` ### Ralph State File Structure ```markdown # .claude/ralph-loop.local.md ## Session: auth-system-design-20260118 ## Completion Promise: Recommendation ready at >90% confidence ### Iteration History #### Iteration 1 (BoT) - **Pattern**: Breadth of Thought - **Duration**: 18 minutes - **Confidence Achieved**: 78% - **Key Findings**: 8 approaches explored, 5 retained above 40% - **Next Pattern Recommendation**: ToT to optimize top 3 - **Promise Status**: NOT MET (78% < 90%) #### Iteration 2 (ToT) - **Pattern**: Tree of Thoughts - **Duration**: 22 minutes - **Confidence Achieved**: 85% - **Key Findings**: JWT with JWKS rotation emerged as optimal - **Next Pattern Recommendation**: AR to validate before claiming >90% - **Promise Status**: NOT MET (85% < 90%) #### Iteration 3 (AR) - **Pattern**: Adversarial Reasoning - **Duration**: 15 minutes - **Confidence Achieved**: 92% - **Key Findings**: 2 critical attacks mitigated, residual risk acceptable - **Promise Status**: MET (92% > 90%) ### Current State - **Active Iteration**: 3 (complete) - **Total Duration**: 55 minutes - **Final Confidence**: 92% - **Exit Approved**: YES ``` --- ## When to Use Ralph-Loop Integration **Use ralph-loop when:** - High confidence threshold required (>90%) - Complex multi-pattern orchestration needed - Self-correcting iteration is valuable - Long-running analysis benefits from checkpointed persistence - Problem may require multiple reasoning pattern switches - You cannot afford premature conclusion **Do not use ralph-loop when:** - Single-pattern analysis is sufficient - Time pressure requires rapid decision (use RTR instead) - Problem is well-understood with clear solution - Iteration overhead exceeds benefit - Confidence threshold is low (<80%) **Decision Matrix:** | Scenario | Use Ralph? | Rationale | |----------|------------|-----------| | Security architecture requiring >90% validation | Yes | High stakes, needs iterative AR passes | | Quick debugging with known patterns | No | Overhead exceeds benefit | | Novel problem with unknown solution space | Yes | May need multiple BoT iterations | | Production incident requiring immediate action | No | Use RTR, ralph adds latency | | Complex trade-off requiring stakeholder buy-in | Yes | DR + NDF may need multiple iterations | --- ## Iteration Safeguards ### Hard Limits Ralph-loop MUST enforce these limits to prevent runaway iterations: - **MAX_ITERATIONS**: 5 (default) - **MAX_TOKENS_PER_ITERATION**: 50,000 - **MAX_TOTAL_TIME**: 30 minutes - **CONFIDENCE_PLATEAU_THRESHOLD**: 3 iterations with <2% improvement → stop ### Stop Conditions (ANY triggers exit) 1. Confidence >= target (success) 2. MAX_ITERATIONS reached (bounded failure) 3. Confidence plateau detected (diminishing returns) 4. Time limit exceeded (timeout) 5. User interrupt (manual stop) 6. Error in pattern execution (fail-safe) ```markdown ## Stop Condition Evaluation Order 1. Check for errors/interrupts (fail-safe, highest priority) 2. Check confidence >= target (success condition) 3. Check iteration count >= MAX_ITERATIONS 4. Check time elapsed >= MAX_TOTAL_TIME 5. Check plateau detection (last 3 iterations) If ANY condition triggers → EXIT immediately with status report ``` ### Safeguard Configuration ```json { "iteration_safeguards": { "max_iterations": 5, "max_tokens_per_iteration": 50000, "max_total_time_minutes": 30, "plateau_detection": { "window_size": 3, "min_improvement_percent": 2 }, "exit_on_error": true, "allow_user_override": true } } ``` --- ## Iteration Log Template Track all iterations systematically: | Iteration | Pattern | Confidence | Delta | Time | Decision | |-----------|---------|------------|-------|------|----------| | 1 | [pattern] | [X]% | - | [Xm] | continue/stop | | 2 | [pattern] | [Y]% | +Z% | [Xm] | continue/stop | | ... | | | | | | ### Plateau Detection **Rule**: If iterations 3, 4, 5 all show delta < 2%, STOP. ```markdown ## Plateau Detection Example | Iteration | Confidence | Delta | Plateau Count | |-----------|------------|-------|---------------| | 1 | 72% | - | 0 | | 2 | 78% | +6% | 0 | | 3 | 79% | +1% | 1 (< 2%) | | 4 | 80% | +1% | 2 (< 2%) | | 5 | 80.5% | +0.5% | 3 (< 2%) → STOP | **Decision**: Plateau detected at iteration 5. Further iterations unlikely to reach 90% target. Exit with 80.5% confidence and document gap. ``` ### Iteration Log Example ```markdown ## Ralph-Loop Iteration Log: auth-system-design | Iter | Pattern | Confidence | Delta | Time | Cumulative | Decision | |------|---------|------------|-------|------|------------|----------| | 1 | BoT | 65% | - | 12m | 12m | continue | | 2 | ToT | 78% | +13% | 15m | 27m | continue | | 3 | AR | 85% | +7% | 10m | 37m | STOP (time limit approaching) | **Exit Reason**: MAX_TOTAL_TIME approaching (37m/30m - override allowed) **Final Confidence**: 85% **Gap to Target**: 5% (target was 90%) **Recommendation**: Document remaining uncertainty, proceed with caveats ``` --- ## Pattern Switching During Iteration ### When to Re-evaluate Pattern Selection If after iteration N: - Confidence stuck → Re-score IR-v2 dimensions - New information → May change optimal pattern - Different pattern scores higher → SWITCH (with handover) ### Pattern Switch Decision Flow ``` After Iteration N: ├─ Confidence increased significantly (>5%)? │ └─ YES → Continue with current pattern │ └─ NO → Re-score IR-v2 dimensions │ ├─ New pattern scores higher? │ └─ YES → Initiate pattern switch with handover │ └─ NO → Continue current pattern (1 more iteration) │ └─ 2 consecutive low-improvement iterations? └─ YES → FORCE re-evaluation or STOP └─ NO → Continue ``` ### Pattern Switch Example ```markdown ## Pattern Switch: ToT → HE ### Iteration History | Iter | Pattern | Confidence | Delta | |------|---------|------------|-------| | 1 | ToT | 65% | - | | 2 | ToT | 68% | +3% (low) | ### Re-evaluation Trigger - Delta < 5% for 2 iterations - Re-scoring IR-v2 dimensions with new information ### IR-v2 Re-scoring **New Information**: Error logs reveal intermittent pattern **Original Scores**: ToT (4.2), HE (3.8) **Updated Scores**: ToT (3.5), HE (4.6) **Reason**: Problem is actually root cause diagnosis, not optimization ### Switch Decision - **From**: ToT (optimization) - **To**: HE (hypothesis elimination) - **Handover**: ToT findings become HE initial hypotheses ### Handover Package ```markdown ## Handover: ToT → HE ### Findings from ToT (Iterations 1-2) - Explored 8 optimization paths - Best path: JWT rotation (68% confidence) - Blocker: Intermittent failures not explained by any path ### Reframing for HE - **Symptom**: Intermittent auth failures - **Initial Hypotheses** (from ToT paths): - H1: Token expiry edge case - H2: Clock drift between services - H3: Race condition in refresh flow - H4: External IdP latency ``` ### Iteration 3: HE | Iter | Pattern | Confidence | Delta | |------|---------|------------|-------| | 3 | HE | 82% | +14% | **Result**: Pattern switch successful. HE identified clock drift (H2). ``` ### Switch Safeguards - **Max switches per session**: 2 (prevent pattern thrashing) - **Handover required**: Cannot switch without documenting state - **Cooldown**: Minimum 1 iteration before re-switching - **User notification**: Pattern switch logged and visible ### Oscillation Detection **Oscillation = switching back to a previously used pattern** If Pattern A -> B -> A detected: - STOP immediately - Flag as "methodology conflict" - Report both patterns' findings - Escalate for human decision **Prevention**: Track all patterns used in session. Block any switch to already-used pattern. --- ## Integration with IR-v2 Orchestration ### Ralph-Wrapped IR-v2 Session ```markdown ## Ralph-Loop Session: [Problem Name] ### Completion Promise <promise>Recommendation ready at >90% confidence with all critical attacks mitigated</promise> ### IR-v2 Dimension Scores | Dimension | Score | |-----------|-------| | Sequential Dependencies | 2 | | Criteria Clarity | 4 | | Solution Space Known | 2 | | Single Answer Needed | 4 | | Evidence Available | 3 | | Opposing Valid Views | 3 | | Problem Novelty | 4 | | Robustness Required | 5 | | Solution Exists | 1 | | Time Pressure | 2 | | Stakeholder Complexity | 3 | ### Initial Pattern Selection **Primary**: BoT (4.35) - Unknown solution space needs exploration **Secondary**: ToT (3.80) - Will optimize once space mapped **Validation**: AR (3.90) - Required for >90% confidence claim ### Orchestration Plan ``` Ralph Loop Wrapper ├─ Iteration 1: BoT exploration → Target: Map solution space ├─ Iteration 2: ToT optimization → Target: Select optimal solution ├─ Iteration 3: AR validation → Target: >90% confidence └─ Exit: <promise>Recommendation ready at >90% confidence</promise> ``` --- ## Ralph + Pattern Integration Examples ### Example 1: BoT → ToT → AR Chain ```markdown ## Problem: Design distributed caching strategy ## Promise: Architecture validated with >90% confidence ### Iteration 1: BoT Exploration **Objective**: Map all viable caching approaches **Entry Criteria**: Unknown solution space **Exit Criteria**: 5+ viable approaches identified **Execution**: 1. Generate 8-10 distinct caching approaches 2. Explore each with strengths/weaknesses analysis 3. Conservative pruning (keep >40%) 4. Rank by viability **Results**: - Approaches explored: 8 - Retained: 6 (above 40% confidence) - Top 3: Write-through (72%), Eventual (68%), CRDT (65%) - Confidence: 78% **Promise Check**: NOT MET (78% < 90%) **Next Iteration**: ToT to optimize top 3 approaches --- ### Iteration 2: ToT Optimization