Claude Learns.Eliminate

# /eliminate - Scientific Process of Elimination Debugging

**Syntax:** `/claude-learns.eliminate [symptom_description]`

Initiate systematic elimination-based debugging using the scientific method with subagent orchestration.

---

## Ralph-Loop Integration

**CRITICAL**: Before starting elimination, check if this is being called from a ralph session.

### Detect Ralph Context

```python
# Check for active ralph session
list_memories()

# Look for any memory named "ralph-*" with status: paused-elimination
# If found, this elimination was triggered by ralph being stuck

If ralph context detected:

1. Read ralph session memory to understand what was being attempted
2. Note the iteration where ralph got stuck
3. After fix: Update ralph session memory with:
   • Fix description
   • Patterns learned
   • Status: active (signals ralph to resume)

Example Ralph Context

# From ralph session memory
Session: feature-auth-system
Status: paused-elimination
Current Iteration: 5
Blocker:
  symptom: "Tests failing with ECONNREFUSED"
  error_count: 3
  first_seen_iteration: 3

When elimination completes, write back:

edit_memory("ralph-feature-auth-system", 
  old="Status: paused-elimination",
  new="Status: active",
  mode="literal")

edit_memory("ralph-feature-auth-system",
  old="Blocker:",
  new="""Blocker: RESOLVED
Resolution:
  symptom: "Tests failing with ECONNREFUSED"
  root_cause: "Mock server not started before tests"
  fix: "Added beforeAll() hook to start mock server"
  iteration_resolved: 5
  
Patterns Discovered:""",
  mode="literal")

---

Overview

This command implements Sherlock Holmes' famous maxim: "When you have eliminated the impossible, whatever remains, however improbable, must be the truth."

Architecture: You (Claude) act as the orchestrator, delegating work to specialized subagents via the Task tool. Each subagent completes its phase and returns control to you.

---

Orchestrator Pattern

IMPORTANT: You are the orchestrator. Do NOT do all the work yourself. Delegate to subagents.

Your Role as Orchestrator

1. Initialize the session via script
2. Launch subagents for specific tasks
3. Validate subagent outputs via script gates
4. Coordinate the iterative loop
5. Make decisions on convergence and next steps
6. Archive the session when complete

Available Subagents

Agent	Purpose	Launch Via
HypothesisAgent	Generate hypotheses from context	Task(subagent_type="general-purpose")
ResearchAgent	Search web for prior art	Task(subagent_type="general-purpose")
CodeAnalysisAgent	Analyze code paths with Serena	Task(subagent_type="general-purpose")
TestRunnerAgent	Execute discriminating tests	Task(subagent_type="general-purpose")

Script Gates (Enforced Between Phases)

Script	Purpose	When to Run
eliminate_init.py	Initialize session	Before HypothesisAgent
eliminate_next.py	Get next hypothesis	Before each test iteration
eliminate_checkpoint.py	Record test, update confidences	After TestRunnerAgent
eliminate_archive.py	Archive completed session	After convergence

---

Orchestrator Workflow

Phase 0: Check Ralph Context (FIRST)

# ALWAYS check for ralph context before anything else
list_memories()

# Look for memories matching "ralph-*" pattern
# Read any that have status: paused-elimination

for memory in memories:
    if memory.startswith("ralph-") and "paused-elimination" in read_memory(memory):
        # This elimination was triggered by ralph
        ralph_context = read_memory(memory)
        # Extract: session_name, iteration, blocker symptom
        # Use this context to inform hypothesis generation

If ralph context found:

• Note the session name for later update
• Use the blocker symptom as the primary symptom
• Consider patterns from ralph's progress log

---

Phase 1: Initialize

# Run BEFORE launching HypothesisAgent
python .claude/scripts/elimination/eliminate_init.py \
  --symptom "$ARGUMENTS" \
  --interactive

If session already exists, ask user: resume or start fresh?

Phase 2: Launch HypothesisAgent

Task(
  subagent_type="general-purpose",
  description="Generate elimination hypotheses",
  prompt="""
You are a HypothesisAgent for elimination debugging.

SYMPTOM: {symptom}
PROJECT: {project_path}

YOUR TASK:
1. Read .elimination/learned/heuristics.yaml for matching patterns
2. Read .elimination/config.yaml for confidence thresholds
3. Read .serena/memories/elimination_patterns.md for project patterns
4. Generate 3-7 hypotheses across categories:
   - Code: Logic errors, bugs, type mismatches
   - Configuration: Env vars, settings, feature flags
   - Dependencies: Version conflicts, API changes
   - Data: Invalid input, state corruption, edge cases
   - Infrastructure: Resource exhaustion, network issues
   - Concurrency: Race conditions, deadlocks
5. Assign initial confidence (use heuristics priors if available)
6. Write each hypothesis to .elimination/active/hypotheses/hyp-{id}.yaml

RETURN FORMAT:
## Hypotheses Generated

| ID | Category | Description | Confidence |
|----|----------|-------------|------------|
| H1 | {cat} | {desc} | {score} |
| H2 | {cat} | {desc} | {score} |
...

Files written: {list of files created}

Do NOT proceed to testing. Return control to orchestrator.
"""
)

Phase 3: Validate Hypotheses (GATE)

After HypothesisAgent returns:

# Verify hypotheses were written
ls .elimination/active/hypotheses/

If no files exist, the gate fails. Ask HypothesisAgent to retry.

Phase 4: Iterative Loop

LOOP until convergence:

  # 4a. Get next hypothesis to test
  python .claude/scripts/elimination/eliminate_next.py

  # Parse output to get: hypothesis_id, description, confidence

  # 4b. (Optional) Launch ResearchA