ralph-loop-integration

What this skill does

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