ralph-loop-integration

name	ralph-loop-integration
description	Persistent iteration wrapper for cognitive reasoning patterns using ralph-loop's Stop hook mechanism. Use when high confidence (>90%) is required, complex multi-pattern orchestration needs iterative refinement, self-correcting analysis is needed, or long-running tasks require checkpointed persistence. Wraps IR-v2 patterns in completion promise-gated loops.
license	MIT

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

# .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)

## 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

{
  "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.

## 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

## 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

## 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: Recommendation ready at >90% confidence

---

## 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