smith-ralph
Ralph Loop integration patterns for iterative AI development. Use when starting Ralph loops, managing iterations, or recovering from context compaction. Covers TDD, debugging, context management, and memory persistence.
When & Why to Use This Skill
The smith-ralph skill provides advanced integration patterns for iterative AI development using the Ralph Loop framework. It optimizes the agent's ability to handle complex, multi-step engineering tasks by establishing clear iteration boundaries, managing rapid context consumption, and ensuring state persistence through memory synchronization. This skill is essential for maintaining project continuity during context compaction and executing structured workflows like TDD and systematic debugging.
Use Cases
- Iterative Software Development: Implementing complex features using a Test-Driven Development (TDD) cycle where the agent iterates through implementation and testing until specific 'promises' are met.
- Advanced Debugging: Systematically identifying root causes by forming hypotheses and executing iterative tests, utilizing the '5 Whys' and delta debugging patterns.
- Context Recovery and Persistence: Managing long-running development sessions by persisting task states to external memory (Serena) before context compaction and resuming seamlessly afterward.
- Structured Task Decomposition: Breaking down large-scale projects into manageable phase milestones with defined quality gates and atomic commit strategies to track progress.
| name | smith-ralph |
|---|---|
| description | Ralph Loop integration patterns for iterative AI development. Use when starting Ralph loops, managing iterations, or recovering from context compaction. Covers TDD, debugging, context management, and memory persistence. |
Ralph Loop Integration
- Load if: Starting
/ralph-loop, managing iterations, recovering from compaction - Prerequisites: @smith-ctx/SKILL.md,
@smith-git/SKILL.md,@smith-serena/SKILL.md
CRITICAL: Ralph Fundamentals (Primacy Zone)
Ralph = iterative prompt loop: Same prompt fed repeatedly, Claude sees previous work in files.
Essential patterns:
- Clear completion criteria with
<promise>tag --max-iterationsas safety limit (always set)- Atomic commits mark iteration boundaries
- Serena memory persists state across compaction
Skills Integration
TDD Workflow (smith-tests)
Pattern: test → implement → run pytest → iterate until <promise>TESTS PASS</promise>.
Each test file = iteration boundary. Commit after green.
Debugging Workflow (smith-validation)
Pattern: hypothesis → test → eliminate → iterate until <promise>ROOT CAUSE FOUND</promise>.
- Strong Inference: Each hypothesis test = one iteration
- 5 Whys: Each "Why?" deepening = one iteration
- Delta Debugging: Split → test → recurse
Task Decomposition (smith-dev)
Pattern: Phase milestones = iteration boundaries. Quality gates between.
Phase 1: [milestone] + tests
Phase 2: [milestone] + tests
Output <promise>COMPLETE</promise> after all phases.
Exploration Workflow (smith-guidance)
Ralph = structured exploration: Read files → Form hypothesis → Design test → Execute → Loop.
Context Management
Ralph burns context rapidly. ~1-3.5k tokens per iteration.
Compaction strategy:
- At 60%: Prepare retention criteria, continue
- At 70%:
/compact, persist Ralph state to Serena memory - After compaction:
read_memory()to resume
Essential retention:
- Iteration number
- Hypotheses tested/remaining
- Test results summary
- File:line references
Commit Strategy
Atomic commits mark iteration boundaries.
- Complete iteration (test passes or hypothesis proven)
- Commit with iteration number:
fix(feature): iteration 3 - resolved null check - If regression, use
git bisectto find breaking iteration
Memory Persistence
Serena memories persist Ralph state across compaction.
Memory fields: ralph_[task]_state
- iteration, hypotheses (tested/remaining), test_results, next_action
Sync timing:
- After each iteration:
write_memory() - Before/after compaction:
write_memory()/read_memory()
@smith-tests/SKILL.md- TDD workflow@smith-validation/SKILL.md- Debugging techniques@smith-dev/SKILL.md- Task decomposition- @smith-guidance/SKILL.md - Exploration workflow
- @smith-ctx/SKILL.md - Context management
@smith-git/SKILL.md- Commit patterns@smith-serena/SKILL.md- Memory persistence
ACTION (Recency Zone)
Starting Ralph:
/ralph-loop "[task]" --completion-promise "[DONE]" --max-iterations 20
During iterations:
- Read files before changes
- Form ONE testable hypothesis
- Execute and record result
- Commit if progress made
write_memory()after each iteration
On compaction:
write_memory()with full state- After
/compact:read_memory()to resume