Ralph Skill Review Loop

Overview

A meta-skill that uses the Ralph Wiggum technique to review and improve the Ralph Wiggum prompt generator skills themselves. Runs a continuous improvement loop until skills pass review twice consecutively with no recommendations.

Quick Start

Copy and run this prompt in a Ralph loop:

/ralph-wiggum:ralph-loop "[paste prompt below]" --completion-promise "RALPH_SKILLS_PERFECTED" --max-iterations 100

THE SELF-IMPROVING REVIEW LOOP PROMPT

# Task: Self-Improving Review of Ralph Wiggum Skills

## Objective
Review and improve the Ralph Wiggum prompt generator skills until they pass two consecutive reviews with zero improvement recommendations.

## Target Skills
1. ralph-prompt-builder (Master orchestrator)
2. ralph-prompt-single-task (Single task generator)
3. ralph-prompt-multi-task (Multi-task generator)
4. ralph-prompt-project (Project generator)
5. ralph-prompt-research (Research generator)

Location: .claude/skills/ralph-prompt-*/SKILL.md

## Reference Materials
- RALPH-WIGGUM-TECHNIQUE-COMPREHENSIVE-RESEARCH.md (12,000+ words of best practices)
- skill-builder-package/research/ (skill building best practices)
- skill-builder-package/examples/ (production skill patterns)

---

## STATE MANAGEMENT

### Required State Files
Create these files to track progress:

**RALPH_REVIEW_STATE.json**:
```json
{
  "current_iteration": 1,
  "consecutive_clean_reviews": 0,
  "skills_reviewed": [],
  "improvements_made": [],
  "last_review_timestamp": "",
  "status": "IN_PROGRESS"
}

RALPH_REVIEW_LOG.md:

# Ralph Skills Review Log

## Iteration History
[Append each iteration's findings here]

STEP 1: ORIENTATION (Every Iteration)

Read current state:

cat RALPH_REVIEW_STATE.json
cat RALPH_REVIEW_LOG.md | tail -50
git log --oneline -5
ls -la .claude/skills/ralph-prompt-*/

Check: How many consecutive clean reviews do we have?

If 2 or more: Output RALPH_SKILLS_PERFECTED
If less than 2: Continue to Step 2

STEP 2: COMPREHENSIVE SKILL REVIEW

Review Framework

For EACH skill in ralph-prompt-*, evaluate against:

2.1 Ralph Technique Alignment (from research)

Clear completion criteria defined
Includes self-verification commands
Has TDD/iteration approach
Includes "If Stuck" guidance
Uses completion tags correctly
Recommends appropriate max-iterations
Follows "deterministically bad" philosophy (failures are fixable)

2.2 Skill Structure Quality

YAML frontmatter complete (name, description with triggers)
Progressive disclosure (overview → details → examples)
Quick Start section exists and is actionable
Examples are realistic and complete
Best practices section included
Integration with Ralph loop documented

2.3 Content Completeness

All sections properly filled (no placeholders)
Examples match the skill type
Verification commands are real and runnable
Edge cases addressed
Cross-references to related skills

2.4 Prompt Template Quality

Templates follow research best practices
Success criteria are measurable
Phase structure is clear (for multi-phase)
State tracking included
Progress tracking pattern included

Review Process

For each skill:

Read the SKILL.md file completely
Compare against RALPH-WIGGUM-TECHNIQUE-COMPREHENSIVE-RESEARCH.md
Check against all 16 criteria above
Document findings in REVIEW_FINDINGS.md

Review Output Format

Create/update REVIEW_FINDINGS.md:

# Review Findings - Iteration [N]

## Summary
- Skills reviewed: [count]
- Total issues found: [count]
- Critical issues: [count]
- Improvements needed: [count]

## ralph-prompt-builder
### Passing
- [x] Criterion that passes

### Issues Found
- [ ] [CRITICAL/HIGH/MEDIUM/LOW] Issue description
  - Location: [section/line]
  - Current: [what exists]
  - Should be: [what it should be]
  - Fix: [specific fix]

## ralph-prompt-single-task
[... same format]

## ralph-prompt-multi-task
[... same format]

## ralph-prompt-project
[... same format]

## ralph-prompt-research
[... same format]

## Recommendations Summary
### Must Fix (Critical/High)
1. [Recommendation 1]
2. [Recommendation 2]

### Should Fix (Medium)
1. [Recommendation 3]

### Nice to Have (Low)
1. [Recommendation 4]

## Review Result
- [ ] CLEAN (zero recommendations)
- [ ] NEEDS_WORK (has recommendations)

STEP 3: IMPLEMENT IMPROVEMENTS

If REVIEW_FINDINGS.md shows NEEDS_WORK:

3.1 Prioritize Fixes

Work in this order:

Critical issues (breaks functionality)
High issues (significantly impacts quality)
Medium issues (improves quality)
Low issues (polish)

3.2 Implement Each Fix

For each recommendation:

Read the target skill file
Implement the specific fix
Verify the fix addresses the issue
Commit the change:

git add .claude/skills/ralph-prompt-[name]/SKILL.md
git commit -m "Improve ralph-prompt-[name]: [brief description]

- [Change 1]
- [Change 2]

Part of Ralph skills self-improvement loop iteration [N]"

3.3 Track Improvements

Update RALPH_REVIEW_STATE.json:

{
  "improvements_made": [
    {
      "iteration": N,
      "skill": "ralph-prompt-X",
      "issue": "description",
      "fix": "what was done"
    }
  ]
}

STEP 4: POST-IMPROVEMENT VERIFICATION

After implementing fixes:

4.1 Verify Each Skill Still Works

For each modified skill:

YAML frontmatter is valid
All sections render correctly
Examples are syntactically correct
No broken references

4.2 Check for Regressions

No content accidentally deleted
Cross-references still valid
Templates still complete

4.3 Run Syntax Check

# Verify YAML frontmatter
for f in .claude/skills/ralph-prompt-*/SKILL.md; do
  head -20 "$f" | grep -E "^(name:|description:)"
done

STEP 5: UPDATE STATE

Update RALPH_REVIEW_STATE.json:

If review was CLEAN (zero recommendations):

{
  "consecutive_clean_reviews": [previous + 1],
  "last_review_result": "CLEAN",
  "last_review_timestamp": "[timestamp]"
}

If review was NEEDS_WORK:

{
  "consecutive_clean_reviews": 0,
  "last_review_result": "NEEDS_WORK",
  "improvements_this_iteration": [count],
  "last_review_timestamp": "[timestamp]"
}

Update RALPH_REVIEW_LOG.md:

## Iteration [N] - [timestamp]

### Review Result
[CLEAN/NEEDS_WORK]

### Issues Found
- [Issue 1]
- [Issue 2]

### Fixes Applied
- [Fix 1]
- [Fix 2]

### State After
- Consecutive clean reviews: [N]
- Total improvements to date: [N]

STEP 6: LOOP DECISION

Check Termination Condition

Read RALPH_REVIEW_STATE.json:

cat RALPH_REVIEW_STATE.json | jq '.consecutive_clean_reviews'

If consecutive_clean_reviews >= 2:

Skills have passed two consecutive reviews with zero recommendations.

Create RALPH_SKILLS_VALIDATION_COMPLETE.md:

# Ralph Skills Validation Complete

## Summary
- Total iterations: [N]
- Total improvements made: [count]
- Final state: All skills validated

## Skills Validated
1. ralph-prompt-builder - PASSED
2. ralph-prompt-single-task - PASSED
3. ralph-prompt-multi-task - PASSED
4. ralph-prompt-project - PASSED
5. ralph-prompt-research - PASSED

## Validation Criteria Met
All 16 review criteria passing for all 5 skills.

## Timestamp
[ISO timestamp]

Output: RALPH_SKILLS_PERFECTED

If consecutive_clean_reviews < 2:

Continue to next iteration (loop back to STEP 1)

REVIEW CRITERIA REFERENCE (Quick Check)

Ralph Technique Alignment

Clear completion criteria
Self-verification commands
TDD/iteration approach
"If Stuck" guidance
tags used correctly
Appropriate max-iterations recommendations
Deterministically bad philosophy

Skill Structure Quality

Complete YAML frontmatter
Progressive disclosure
Actionable Quick Start
Realistic examples
Best practices section
Ralph loop integration docs

Content Completeness

No placeholders
Matching examples
Real verification commands

ESCAPE HATCH

If stuck after 50 iterations without reaching 2 consecutive clean reviews:

Document the recurring issues in RALPH_REVIEW_BLOCKERS.md
List which criteria keep failing
Identify if criteria are too strict
Output: RALPH_REVIEW_BLOCKED

PROGRESS TRACKING

Every 5 iterations, summarize:

PROGRESS SUMMARY - Iteration [N]
================================
Started: [timestamp]
Current: [timestamp]
Consecutive clean reviews: [N]/2

Skills Status:
- ralph-prompt-builder: [X/16 criteria passing]
- ralph-prompt-single-task: [X/16 criteria passing]
- ralph-prompt-multi-task: [X/16 criteria passing]
- ralph-prompt-project: [X/16 criteria passing]
- ralph-prompt-research: [X/16 criteria passing]

Improvements made: [total count]
Remaining issues: [count]

COMPLETION CONDITIONS

Output RALPH_SKILLS_PERFECTED ONLY when:

All 5 skills reviewed
All 16 criteria checked per skill
Zero recommendations in current review
Zero recommendations in previous review
consecutive_clean_reviews >= 2 in state file
RALPH_SKILLS_VALIDATION_COMPLETE.md created
All changes committed

SAFETY LIMITS

Maximum iterations: 100
Expected completion: 20-40 iterations
Budget alert: If > 50 iterations, evaluate if criteria are too strict


---

## Usage Instructions

### 1. Initialize State Files

Before running, create the initial state:

```bash
# Create state file
cat > RALPH_REVIEW_STATE.json << 'EOF'
{
  "current_iteration": 0,
  "consecutive_clean_reviews": 0,
  "skills_reviewed": [],
  "improvements_made": [],
  "last_review_timestamp": "",
  "status": "NOT_STARTED"
}
EOF

# Create log file
cat > RALPH_REVIEW_LOG.md << 'EOF'
# Ralph Skills Review Log

## Overview
Self-improving review loop for Ralph Wiggum prompt generator skills.

## Target: Two consecutive clean reviews

---

## Iteration History

EOF

2. Run the Loop

/ralph-wiggum:ralph-loop "[THE PROMPT ABOVE]" \
  --completion-promise "RALPH_SKILLS_PERFECTED" \
  --max-iterations 100

3. Monitor Progress

# Check current state
cat RALPH_REVIEW_STATE.json | jq '.'

# See recent activity
tail -30 RALPH_REVIEW_LOG.md

# Check how many clean reviews
cat RALPH_REVIEW_STATE.json | jq '.consecutive_clean_reviews'

4. After Completion

Review the outputs:

RALPH_REVIEW_STATE.json - Final state
RALPH_REVIEW_LOG.md - Complete history
REVIEW_FINDINGS.md - Last review details
RALPH_SKILLS_VALIDATION_COMPLETE.md - Success certificate
Git log - All improvements committed

Why This Works

State Tracking: JSON state file persists across iterations
Clear Criteria: 16 specific, measurable review criteria
Self-Correction: Each iteration reads previous results and fixes issues
Termination Condition: Two consecutive clean reviews ensures stability
Evidence-Based: All findings documented, all fixes tracked
Git Integration: Every improvement committed for auditability

Expected Behavior

Iteration 1-5: Discovery phase

Identify initial issues across all skills
Begin fixing critical issues

Iteration 6-15: Improvement phase

Systematic fixes
Quality improvements
Cross-consistency

Iteration 16-25: Stabilization phase

Fewer issues found
Polish and edge cases
Approaching clean reviews

Iteration 26-40: Validation phase

First clean review achieved
Verify no regressions
Second clean review achieved
Completion

Customization

Stricter Review

Add more criteria to the review framework.

Faster Completion

Reduce to "one clean review" by changing:

consecutive_clean_reviews >= 1

Focus on Specific Skills

Modify the target skills list in the prompt.

ralph-skill-review-loop