Ralph Ify

RALPH-ify: Transform Workflows into Iterative Architecture

Overview

RALPH-ify is a meta-skill that transforms any workflow, existing skill, or business process into a RALPH-style iterative architecture. It generates complete, ready-to-run skills with:

• Three-phase execution (Planning → Iterative Execution → Assembly)
• Quality gates with specific feedback for refinement
• State persistence for resumability
• Audit logging for transparency

Invocation

/ralph-ify <input> [--name SKILL_NAME]

Arguments

Input Formats

The skill accepts multiple input formats:

1. Text description: "Process invoices and send payment reminders"
2. File path: /path/to/workflow-description.md
3. Existing skill: .claude/skills/document-studio (to upgrade a non-RALPH skill)
4. Meeting transcript: Path to a transcript file describing a process

Execution Flow

┌─────────────────────────────────────────────────────────────────┐
│                     PHASE 1: ANALYSIS                           │
├─────────────────────────────────────────────────────────────────┤
│  1. Parse input (detect format: text/file/skill)                │
│  2. Extract workflow structure                                   │
│  3. Identify discrete work units                                 │
│  4. Map dependencies between units                               │
│  5. Present analysis summary                                     │
│  6. ──► CHECKPOINT: Get user approval ◄──                       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     PHASE 2: DESIGN                             │
├─────────────────────────────────────────────────────────────────┤
│  1. Generate atomic work units with sizing                       │
│  2. Create PRD schema structure                                  │
│  3. Design quality gates (4-8 per item type)                    │
│  4. Define state file structure                                  │
│  5. Present design summary                                       │
│  6. ──► CHECKPOINT: Get user approval ◄──                       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    PHASE 3: SCAFFOLD                            │
├─────────────────────────────────────────────────────────────────┤
│  1. Generate SKILL.md with three-phase architecture             │
│  2. Create prd-schema.json                                       │
│  3. Create quality-gates.md                                      │
│  4. Create state directory template                              │
│  5. Write all files to .claude/skills/{skill-name}/             │
│  6. Present completion summary                                   │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Analysis

Step 1.1: Detect Input Format

Parse the input to determine its type:

IF input starts with "." or "/" AND is a directory:
    → Existing skill (upgrade mode)
ELSE IF input is a valid file path:
    → File-based workflow description
ELSE:
    → Free-form text description

Step 1.2: Extract Workflow Structure

Read the referenced prompt template: .claude/skills/ralph-ify/prompts/analysis.md

Run the analysis prompt against the input to extract:

• Workflow name: What is this process called?
• Workflow steps: What are the sequential/parallel steps?
• Work units: What are the discrete, atomic tasks?
• Dependencies: Which units depend on others?
• Success criteria: What does "done" look like for each unit?
• Failure modes: What can go wrong?

Step 1.3: Present Analysis Summary

Present findings to the user in this format:

## Workflow Analysis: {workflow_name}

### Identified Work Units ({count})

| ID | Unit Name | Dependencies | Est. Complexity |
|----|-----------|--------------|-----------------|
| 1  | ...       | None         | Low             |
| 2  | ...       | [1]          | Medium          |

### Success Criteria
- Unit 1: [criteria]
- Unit 2: [criteria]

### Potential Failure Modes
- [failure mode 1]
- [failure mode 2]

Step 1.4: User Approval Checkpoint

Use AskUserQuestion to confirm:

• Are the work units correctly identified?
• Are there any missing steps?
• Should any units be split or merged?

Phase 2: Design

Step 2.1: Generate Atomic Work Units

For each identified work unit, ensure it:

• Can be completed in one context window
• Has clear input/output boundaries
• Has measurable success criteria

Step 2.2: Create PRD Schema

Read the template: .claude/skills/ralph-ify/templates/prd-template.json

Generate a PRD schema specific to this workflow:

{
  "version": "1.0",
  "skill": "{skill-name}",
  "config": {
    "maxIterations": {recommended},
    "maxFailuresPerItem": 3
  },
  "items": [
    {
      "id": "{ITEM_TYPE}-001",
      "title": "...",
      "description": "...",
      "priority": 1,
      "status": "pending",
      "dependsOn": []
    }
  ]
}

Step 2.3: Design Quality Gates

Read the prompt: .claude/skills/ralph-ify/prompts/quality-gates.md

For each item type, generate 4-8 quality checks:

## Quality Gate: {item_type}

| Check | Criteria | Pass Threshold | Failure Suggestion |
|-------|----------|----------------|-------------------|
| check_1 | ... | ... | "To fix: ..." |
| check_2 | ... | ... | "To fix: ..." |

**Pass Threshold**: 70% of checks must pass
**Critical Failures**: [checks that auto-fail the gate]

Step 2.4: Define State Structure

Design the state directory:

.{skill-name}/
├── prd.json              # Source of truth for items
├── progress.txt          # Human-readable log
├── segments/             # Per-item outputs (if applicable)
└── output/               # Final assembled outputs

Step 2.5: User Approval Checkpoint

Present the complete design and use AskUserQuestion to confirm:

• Is the PRD structure correct?
• Are the quality gates appropriate?
• Should any gates be added/removed?

Phase 3: Scaffold

Step 3.1: Generate SKILL.md

Read the template: .claude/skills/ralph-ify/templates/skill-template.md

Generate a complete SKILL.md with:

• Frontmatter (name, description, tools, invocation)
• Overview section
• Three-phase execution flow
• Detailed instructions for each phase
• Quality gates section
• State files documentation
• Troubleshooting section

Step 3.2: Create Supporting Files

Generate all supporting files:

1. prd-schema.json: The designed PRD structure
2. quality-gates.md: All quality gate definitions
3. State directory template: Empty directories with README

Step 3.3: Write Files

Write all files to .claude/skills/{skill-name}/:

.claude/skills/{skill-name}/
├── SKILL.md
├── prd-schema.json
├── quality-gates.md
└── state-template/
    ├── .gitkeep
    └── README.md

Step 3.4: Completion Summary

Present a summary:

## RALPH-ified Skill Created

**Skill Name**: {skill-name}
**Location**: .claude/skills/{skill-name}/

### Files Created
- SKILL.md (main skill definition)
- prd-schema.json (PRD structure)
- quality-gates.md (validation criteria)
- state-template/ (state directory)

### Next Steps
1. Review the generated SKILL.md
2. Test with: `/{skill-name} <test-input>`
3. Iterate on quality gates as needed

Quality Gates (for RALPH-ify itself)

Gate 1: Decomposition Quality

Gate 2: Quality Gate Coverage

Gate 3: State Schema Validity

Gate 4: Skill Definition Completeness

State Files

This skill does not maintain persistent state. Each invocation is independent.

Troubleshooting

"Input not recognized"

• Ensure the input is either a valid file path or text description
• For existing skills, provide the full path to the skill directory

"Workflow too complex"

• Break the workflow into smaller sub-workflows
• Run RALPH-ify on each sub-workflow separately

"Quality gates seem wrong"

• Quality gates are generated heuristically; edit them manually after generation
• Focus on measurable, objective criteria

Examples

See .claude/skills/ralph-ify/examples/ for example transformations.