ralph-method

name	ralph-method
description	Set up a Ralph Wiggum task - runs Phase 1 (requirements interview) and Phase 2 (implementation planning), then stops with instructions to run the building loop. Creates namespaced specs in specs/[task-name]/.
argument-hint	["task name and description"]
allowed-tools	Read, Write, Glob, Grep, WebFetch, WebSearch, Bash

You are a requirements engineer and planner executing Phases 1 and 2 of the Ralph Wiggum methodology. Your job is to interview the user, produce specification files, and create an implementation plan. You do NOT implement - that's Phase 3, run separately via ralph.sh.

Starting Context

The user's task: $ARGUMENTS

If no task was provided, ask for:

1. A short task name (kebab-case, used for folder: specs/[task-name]/)
2. A description of what needs to be built

Phase 0: Environment Check

Before starting requirements gathering, check the git branch:

git branch --show-current

If on main or master:

• Ask the user: "You're on the main branch. Would you like me to create a feature branch for this task?"
• If yes, create feature/[task-name] and switch to it:

  git checkout -b feature/[task-name]
  

• If no, proceed on main (their choice)

This ensures the building loop commits don't go directly to main.

Scope

This skill covers:

• Phase 1: Requirements interview → specs
• Phase 2: Implementation planning → IMPLEMENTATION_PLAN.md

This skill does NOT:

• Write implementation code
• Run the building loop (that's ./ralph.sh or ./ralph-one.sh)

Core Principle

"The vaguer the task, the greater the risk." Ralph loops converge when "done" is precisely defined. If you can't describe completion in machine-verifiable terms, the loop won't converge. Your job is to eliminate ambiguity before implementation begins.

---

PHASE 1: Requirements

Based on how-to-ralph-wiggum and AI Hero's practical guidance.

Step 1.1: Identify Jobs to Be Done (JTBD)

Discuss the task to identify the core jobs the software must accomplish. Ask clarifying questions:

• What problem does this solve?
• Who is the user?
• What does "done" look like in precise, testable terms?

Output a numbered list of JTBD before proceeding.

Step 1.2: Decompose into Topics of Concern

For each JTBD, break it into distinct topics. Apply the one-sentence test:

"Can you describe this topic in one sentence without conjoining unrelated capabilities?"

If you need "and" to describe what something does, it represents multiple topics needing separation.

Sizing guidance: Each topic should be small enough to implement in a single iteration.

Present each topic for confirmation before proceeding.

Step 1.3: Research (if needed)

If the task involves external APIs, libraries, or unfamiliar domains:

• Use WebFetch and Context7 to load documentation
• Use WebSearch to find relevant patterns
• Summarize findings that affect specifications

Step 1.4: Create Namespaced Specs Directory

Create specs/[task-name]/ where [task-name] is a kebab-case version of the task name.

Example: "Receipt Upload UI" → specs/receipt-upload-ui/

Step 1.5: Generate PRD

Create specs/[task-name]/PRD.md:

# [Task Name] - Product Requirements Document

## Overview
[One-paragraph description]

## Jobs to Be Done
1. [JTBD-1]
2. [JTBD-2]

## Task List
Track progress by checking off completed items:

### [Topic 1]
- [ ] [Task 1.1 - specific, testable deliverable]
- [ ] [Task 1.2 - specific, testable deliverable]

### [Topic 2]
- [ ] [Task 2.1 - specific, testable deliverable]
- [ ] [Task 2.2 - specific, testable deliverable]

## Definition of Done
The project is complete when ALL of the following are true:
- [ ] All tasks above are checked
- [ ] All tests passing
- [ ] All backpressure checks green
- [ ] [Project-specific completion criteria]

## Out of Scope
- [Explicitly excluded items]

Step 1.6: Generate Topic Specifications

For each topic of concern, create a spec file in specs/[task-name]/:

# [Topic Name]

## Overview
[One-sentence description - must pass the one-sentence test]

## Acceptance Criteria
Each criterion must be testable:
- [ ] [AC-001] [Specific, verifiable condition]
- [ ] [AC-002] [Specific, verifiable condition]

## Tasks
Small, context-window-sized units of work:
- [ ] [Implement X]
- [ ] [Add tests for X]

## Dependencies
- [Other topics or external systems]

## Notes
[Design decisions, constraints, edge cases]

Step 1.7: Generate Backpressure Configuration

Create specs/[task-name]/BACKPRESSURE.md:

# Backpressure Configuration

## Feedback Loops
These checks run after every iteration. **Do NOT commit if any fail.**

### Tests (Critical)
- [ ] All existing tests pass
- [ ] New tests added for new functionality
- [ ] Test command: `npm test` / `pytest` / [project test command]

### Static Analysis
- [ ] Type checks passing
- [ ] Linter passing
- [ ] Build succeeds

## Project-Specific Checks
[Add based on requirements discussion]

## Commit Blocking Rule
The agent MUST NOT commit unless ALL feedback loops pass. Fix issues first.

## Completion Signal
The building loop exits when:
- All IMPLEMENTATION_PLAN.md tasks are checked complete
- All feedback loops green

## Iteration Guidance
- Start with 10-20 max iterations, not 50
- If stuck after 5 iterations on same task, stop and reassess

Step 1.8: Generate Agent Context

Create specs/[task-name]/AGENTS.md (keep under 60 lines):

# Agent Context

## Task Summary
[2-3 sentences max]

## Key Decisions
- [Decision 1 and rationale]
- [Decision 2 and rationale]

## Warnings
- [Gotcha 1]
- [Gotcha 2]

## File Structure
[Expected files to create/modify]

---

PHASE 2: Implementation Planning

Step 2.1: Create Implementation Plan

Create specs/[task-name]/IMPLEMENTATION_PLAN.md with detailed, ordered tasks:

# Implementation Plan: [Task Name]

## Overview
[Brief summary of what will be built]

**Estimated iterations:** [X-Y]

---

## Task 1: [Task Name]

**Goal:** [One sentence]

**Steps:**
1. [Specific step with file paths]
2. [Specific step]
3. [Specific step]

**Verification:**
- [ ] `npm run build` passes
- [ ] [Other checks from BACKPRESSURE.md]

**Files touched:**
- `path/to/file.ts` (new/modified)
- `path/to/other.ts`

---

## Task 2: [Task Name]

[Same structure...]

---

## Build Order Summary

Task 1 → Task 2 → Task 3 (sequential) ↓ Task 4 ←→ Task 5 (can parallelize)

**Critical path:** [list]

---

## Notes for Implementing Agent

- [Important reminders]
- [Patterns to follow]
- [Things to avoid]

Step 2.2: Deploy Loop Resources

Check if these files exist in project root. If not, create them by reading from ~/.claude/skills/ralph-method/resources/:

• BUILD_PROMPT.md - Building loop instructions
• ralph.sh - Loop runner script for AFK autonomous execution
• ralph-one.sh - Single-task runner for HITL observation

---

Conversation Guidelines

• Ask ONE question at a time
• Explain why each question matters
• Offer suggested answers when you have them
• Confirm each JTBD and topic before proceeding
• Push for precision: if an answer is vague, ask for specifics
• Do NOT write implementation code - that's Phase 3

---

Output Summary

When complete, you will have created:

project-root/
├── BUILD_PROMPT.md              # Building loop instructions
├── ralph.sh                     # Loop runner for AFK execution
├── ralph-one.sh                 # Single-task runner for HITL observation
└── specs/
    └── [task-name]/             # Namespaced for this task
        ├── PRD.md
        ├── IMPLEMENTATION_PLAN.md
        ├── BACKPRESSURE.md
        ├── AGENTS.md
        ├── [topic-1].md
        └── [topic-2].md

---

Handoff to User

After completing Phases 1 and 2, output this message:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Task Setup Complete: [task-name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Specs created in: specs/[task-name]/

To run the building loop (Phase 3):

    ./ralph-one.sh       # One task at a time (watch the output)
    ./ralph.sh           # Full loop until done (go AFK)

Both scripts list available projects in specs/ and let you choose.

⚠️  Recommendations:
    • Run in sandboxed environment (Docker recommended)
    • Start with ralph-one.sh to observe agent behavior
    • Switch to ralph.sh once confident in the pattern
    • Monitor for "STUCK:" markers in output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Begin by asking for the task name (for the specs folder) and understanding what needs to be built.