ralph

What this skill does

# ralph (Ouroboros) — Specification-First AI Development

> **Stop prompting. Start specifying.**
>
> *"The beginning is the end, and the end is the beginning."*
> The serpent doesn't repeat — it evolves.

---

## When to use this skill

- **Before writing any code** — expose hidden assumptions with Socratic interviewing
- **Long-running tasks** that need autonomous iteration until verified
- **Vague requirements** — crystallize them into an immutable spec (Ambiguity ≤ 0.2)
- **Tasks requiring guaranteed completion** — loop until verification passes
- **When stuck** — 5 lateral thinking personas break through stagnation
- **Drift detection** — measure how far execution has deviated from original spec

---

## Core Architecture: The Loop

```
    Interview → Seed → Execute → Evaluate
        ↑                           ↓
        └──── Evolutionary Loop ────┘
```

Each cycle **evolves**, not repeats. Evaluation output feeds back as input for the next generation until the system converges.

### Double Diamond

```
    ◇ Wonder          ◇ Design
   ╱  (diverge)      ╱  (diverge)
  ╱    explore      ╱    create
 ╱                 ╱
◆ ──────────── ◆ ──────────── ◆
 ╲                 ╲
  ╲    define       ╲    deliver
   ╲  (converge)     ╲  (converge)
    ◇ Ontology        ◇ Evaluation
```

The first diamond is **Socratic**: diverge into questions, converge into ontological clarity.
The second diamond is **pragmatic**: diverge into design options, converge into verified delivery.

---

## 1. Commands (Full Reference)

| Command | Trigger Keywords | What It Does |
|---------|-----------------|--------------|
| `ooo interview` | `ooo interview`, `interview me`, `clarify requirements`, `socratic questioning` | Socratic questioning → expose hidden assumptions |
| `ooo seed` | `ooo seed`, `crystallize`, `generate seed`, `freeze requirements` | Crystallize interview into immutable spec (Ambiguity ≤ 0.2) |
| `ooo run` | `ooo run`, `execute seed`, `ouroboros run` | Execute via Double Diamond decomposition |
| `ooo evaluate` | `ooo evaluate`, `3-stage check`, `evaluate this`, `verify execution` | 3-stage gate: Mechanical → Semantic → Multi-Model Consensus |
| `ooo evolve` | `ooo evolve`, `evolutionary loop`, `iterate until converged` | Evolutionary loop until ontology converges (similarity ≥ 0.95) |
| `ooo unstuck` | `ooo unstuck`, `I'm stuck`, `think sideways`, `lateral thinking` | 5 lateral thinking personas when stuck |
| `ooo status` | `ooo status`, `am I drifting?`, `drift check`, `session status` | Drift detection + session tracking |
| `ooo ralph` | `ooo ralph`, `ralph`, `don't stop`, `must complete`, `keep going` | Persistent loop until verified — The boulder never stops |
| `ooo setup` | `ooo setup` | Register MCP server (one-time) |
| `ooo help` | `ooo help` | Full reference |

---

## 2. Interview → Specification Flow

### Philosophy: From Wonder to Ontology

> *Wonder → "How should I live?" → "What IS 'live'?" → Ontology* — Socrates

```
   Wonder                          Ontology
     💡                               🔬
"What do I want?"    →    "What IS the thing I want?"
"Build a task CLI"   →    "What IS a task? What IS priority?"
"Fix the auth bug"   →    "Is this the root cause, or a symptom?"
```

### Step 1: Interview (expose hidden assumptions)

```
ooo interview "I want to build a task management CLI"
```

The Socratic Interviewer asks questions until **Ambiguity ≤ 0.2**.

**Ambiguity formula:**
```
Ambiguity = 1 − Σ(clarityᵢ × weightᵢ)

Greenfield: Goal(40%) + Constraint(30%) + Success(30%)
Brownfield: Goal(35%) + Constraint(25%) + Success(25%) + Context(15%)

Threshold: Ambiguity ≤ 0.2 → ready for Seed
```

Example scoring:
```
Goal:       0.9 × 0.4 = 0.36
Constraint: 0.8 × 0.3 = 0.24
Success:    0.7 × 0.3 = 0.21
                        ──────
Clarity             = 0.81
Ambiguity = 1 − 0.81 = 0.19 ≤ 0.2 → ✓ Ready for Seed
```

### Step 2: Seed (crystallize into immutable spec)

```
ooo seed
```

Generates YAML specification:
```yaml
goal: Build a CLI task management tool
constraints:
  - Python 3.14+
  - No external database
  - SQLite for persistence
acceptance_criteria:
  - Tasks can be created
  - Tasks can be listed
  - Tasks can be marked complete
ontology_schema:
  name: TaskManager
  fields:
    - name: tasks
      type: array
    - name: title
      type: string
```

### Step 3: Run (execute via Double Diamond)

```
ooo run seed.yaml
ooo run  # uses seed from conversation context
```

### Step 4: Evaluate (3-stage verification)

```
ooo evaluate <session_id>
```

| Stage | Cost | What It Checks |
|-------|------|----------------|
| **Mechanical** | $0 | Lint, build, tests, coverage |
| **Semantic** | Standard | AC compliance, goal alignment, drift score |
| **Consensus** | Frontier (optional) | Multi-model vote, majority ratio |

Drift thresholds:
- `0.0 – 0.15` — Excellent: on track
- `0.15 – 0.30` — Acceptable: monitor closely
- `0.30+` — Exceeded: course correction needed

---

## 3. Ralph — Persistent Loop Until Verified

```
ooo ralph "fix all failing tests"
/ouroboros:ralph "fix all failing tests"
```

**"The boulder never stops."**
Each failure is data for the next attempt. Only complete success or max iterations stops it.

### How Ralph Works

```
┌─────────────────────────────────┐
│  1. EXECUTE (parallel)          │
│     Independent tasks           │
│     concurrent scheduling       │
├─────────────────────────────────┤
│  2. VERIFY                      │
│     Check completion            │
│     Validate tests pass         │
│     Measure drift vs seed       │
├─────────────────────────────────┤
│  3. LOOP (if failed)            │
│     Analyze failure             │
│     Fix identified issues       │
│     Repeat from step 1          │
├─────────────────────────────────┤
│  4. PERSIST (checkpoint)        │
│     .omc/state/ralph-state.json │
│     Resume after interruption   │
└─────────────────────────────────┘
```

### State File

Create `.omc/state/ralph-state.json` on start:
```json
{
  "mode": "ralph",
  "session_id": "<uuid>",
  "request": "<user request>",
  "status": "running",
  "iteration": 0,
  "max_iterations": 10,
  "last_checkpoint": null,
  "verification_history": []
}
```

### Loop Logic

```
while iteration < max_iterations:
    result = execute_parallel(request, context)
    verification = verify_result(result, acceptance_criteria)
    state.verification_history.append({
        "iteration": iteration,
        "passed": verification.passed,
        "score": verification.score,
        "timestamp": <now>
    })
    if verification.passed:
        save_checkpoint("complete")
        break
    iteration += 1
    save_checkpoint("iteration_{iteration}")
```

### Progress Report Format

```
[Ralph Iteration 1/10]
Executing in parallel...

Verification: FAILED
Score: 0.65
Issues:
- 3 tests still failing
- Type errors in src/api.py

The boulder never stops. Continuing...

[Ralph Iteration 3/10]
Executing in parallel...

Verification: PASSED
Score: 1.0

Ralph COMPLETE
==============
Request: Fix all failing tests
Duration: 8m 32s
Iterations: 3

Verification History:
- Iteration 1: FAILED (0.65)
- Iteration 2: FAILED (0.85)
- Iteration 3: PASSED (1.0)
```

### Cancellation

| Action | Command |
|--------|---------|
| Save checkpoint & exit | `/ouroboros:cancel` |
| Force clear all state | `/ouroboros:cancel --force` |
| Resume after interruption | `ooo ralph continue` or `ralph continue` |

---

## 4. Evolutionary Loop (Evolve)

```
ooo evolve "build a task management CLI"
ooo evolve "build a task management CLI" --no-execute  # ontology-only, fast mode
```

### Flow

```
Gen 1: Interview → Seed(O₁) → Execute → Evaluate
Gen 2: Wonder → Reflect → Seed(O₂) → Execute → Evaluate
Gen 3: Wonder → Reflect → Seed(O₃) → Execute → Evaluate
...until ontology converges (similarity ≥ 0.95) or max 30 generations
```

### Convergence Formula

```
Similarity = 0.5 × name_overlap + 0.3 × type_match + 0.2 × exact_match
Thres