lisa

Lisa

Observable iterative loops for Claude Code — An evolution of the Ralph Wiggum technique.

"I'm going to become a famous jazz musician. And you know what? It's not going to be easy, but I'm going to work hard and I'm going to practice every day." — Lisa Simpson

From Ralph to Lisa

This plugin is inspired by Geoffrey Huntley's Ralph Wiggum technique but has evolved significantly. Like Lisa Simpson compared to Ralph Wiggum, this implementation is more methodical and observable — while preserving the core philosophy of iterative refinement.

The Original Ralph (2025)

Geoffrey Huntley's Ralph was beautifully simple:

while :; do cat PROMPT.md | npx --yes @sourcegraph/amp ; done

Philosophy:

• "Deterministically bad in an undeterministic world"
• Faith in "eventual consistency"
• Errors are tuning opportunities, not failures
• "I haven't blamed the tools; instead, I've looked inside"

The Evolution to Lisa

Lisa preserves Ralph's core philosophy but adds observability and safety:

Aspect	Ralph (Original)	Lisa (This Plugin)
Mechanism	External bash while :; loop	Native Claude Code stop hook
Termination	None (Ctrl+C only)	Completion promises + max iterations
State	None	YAML frontmatter in .claude/lisa-loop.local.md
Progress	Invisible	Auto-detects from IMPLEMENTATION_PLAN.md
Logging	None	Full iteration log with timestamps and metrics
Cleanup	Manual	/lisa:clean handles orphaned files
Orchestration	User must know when to use	Claude proposes automatically
Safety	Infinite loop risk	Required --max-iterations

What's Preserved (The Soul of Ralph)

1. Same prompt, every iteration — The core loop feeds identical input repeatedly
2. Eventual consistency — Trust that iteration leads to success
3. PROMPT.md as source of truth — All behavior defined in the prompt file
4. Errors as feedback — No "failure", only steps toward completion
5. Autonomous operation — No human intervention between iterations

What's Added (Lisa's Features)

Feature	Why It Matters
Completion promises	Clean, verifiable exit instead of Ctrl+C
Auto-detection	<promise>DONE</promise> in prompt = automatic setup
Progress tracking	See Progress: 23/48 during execution
Iteration logging	Debug issues, analyze performance
Max iterations	Safety net against runaway loops
Orphan cleanup	No accumulated PROMPT.md files
Native integration	Works within Claude Code, not external bash

---

Quick Start

Option 1: File-based prompt (Recommended)

# 1. Create your prompt file
cat > PROMPT.md << 'EOF'
# Mission
Build a REST API for todos.

# Requirements
- CRUD operations
- Input validation
- Tests with >80% coverage

# Completion
When all requirements are met: <promise>DONE</promise>
EOF

# 2. Start the loop
/lisa:loop PROMPT.md --max-iterations 50

Option 2: Inline prompt

/lisa:loop "Fix all TypeScript errors. Output <promise>FIXED</promise> when tsc passes." --max-iterations 30

---

How It Works