The Ralph Playbook

During Phase 1 (Define Requirements), use Claude's built-in AskUserQuestionTool to systematically explore JTBD, topics of concern, edge cases, and acceptance criteria through structured interview before writing specs.

When to use: Minimal/vague initial requirements, need to clarify constraints, or multiple valid approaches exist.

Invoke: "Interview me using AskUserQuestion to understand [JTBD/topic/acceptance criteria/...]"

Claude will ask targeted questions to clarify requirements and ensure alignment before producing specs/*.md files.

Flow:

1. Start with known information →
2. Claude interviews via AskUserQuestion →
3. Iterate until clear →
4. Claude writes specs with acceptance criteria →
5. Proceed to planning/building

No code or prompt changes needed – this simply enhances Phase 1 using existing Claude Code capabilities.

Inspiration - Thariq's X post

Geoff's Ralph implicitly connects specs → implementation → tests through emergent iteration. This enhancement would make that connection explicit by deriving test requirements during planning, creating a direct line from "what success looks like" to "what verifies it."

This enhancement connects acceptance criteria (in specs) directly to test requirements (in implementation plan), improving backpressure quality by:

• Preventing "no cheating" – Can't claim done without required tests derived from acceptance criteria
• Enabling TDD workflow – Test requirements known before implementation starts
• Improving convergence – Clear completion signal (required tests pass) vs ambiguous ("seems done?")
• Maintaining determinism – Test requirements in plan (known state) not emergent (probabilistic)

Compatibility with Core Philosophy

The Prescriptiveness Balance

The critical distinction:

Acceptance criteria (in specs) = Behavioral outcomes, observable results

• ✓ "Extracts 5-10 dominant colors from any uploaded image"
• ✓ "Processes images <5MB in <100ms"
• ✓ "Handles edge cases: grayscale, single-color, transparent backgrounds"

Test requirements (in plan) = Verification points derived from acceptance criteria

• ✓ "Required tests: Extract 5-10 colors, Performance <100ms"

Implementation approach (up to Ralph) = Technical decisions

• ✗ "Use K-means clustering with 3 iterations"

The key: Specify WHAT to verify (outcomes), not HOW to implement (approach).

This maintains "Let Ralph Ralph" principle - Ralph decides implementation details while having clear success signals.

Architecture: Three-Phase Connection

Phase 1: Requirements Definition
    specs/*.md + Acceptance Criteria
    ↓
Phase 2: Planning (derives test requirements)
    IMPLEMENTATION_PLAN.md + Required Tests
    ↓
Phase 3: Building (implements with tests)
    Implementation + Tests → Backpressure

Phase 1: Requirements Definition

During the human + LLM conversation that produces specs:

• Discuss JTBD and break into topics of concern
• Use subagents to load external context as needed
• Discuss and define acceptance criteria – what observable, verifiable outcomes indicate success
• Keep criteria behavioral (outcomes), not implementation (how to build it)
• LLM writes specs including acceptance criteria however makes most sense for the spec
• Acceptance criteria become the foundation for deriving test requirements in planning phase

Phase 2: Planning Mode Enhancement

Modify PROMPT_plan.md instruction 1 to include test derivation. Add after the first sentence:

For each task in the plan, derive required tests from acceptance criteria in specs - what specific outcomes need verification (behavior, performance, edge cases). Tests verify WHAT works, not HOW it's implemented. Include as part of task definition.

Phase 3: Building Mode Enhancement

Modify PROMPT_build.md instructions:

Instruction 1: Add after "choose the most important item to address":

Tasks include required tests - implement tests as part of task scope.

Instruction 2: Replace "run the tests for that unit of code" with:

run all required tests specified in the task definition. All required tests must exist and pass before the task is considered complete.

Prepend new guardrail (in the 9s sequence):

999. Required tests derived from acceptance criteria must exist and pass before committing. Tests are part of implementation scope, not optional. Test-driven development approach: tests can be written first or alongside implementation.

Some acceptance criteria resist programmatic validation:

• Creative quality – Writing tone, narrative flow, engagement
• Aesthetic judgments – Visual harmony, design balance, brand consistency
• UX quality – Intuitive navigation, clear information hierarchy
• Content appropriateness – Context-aware messaging, audience fit

Solution: Add LLM-as-Judge tests as backpressure with binary pass/fail.

LLM reviews are non-deterministic (same artifact may receive different judgments across runs). This aligns with Ralph philosophy: "deterministically bad in an undeterministic world." The loop provides eventual consistency through iteration–reviews run until pass, accepting natural variance.

What Needs to Be Created (First Step)

Create two files in src/lib/:

src/lib/
  llm-review.ts          # Core fixture - single function, clean API
  llm-review.test.ts     # Reference examples showing the pattern (Ralph learns from these)

llm-review.ts - Binary pass/fail API Ralph discovers:

interface ReviewResult {
  pass: boolean;
  feedback?: string; // Only present when pass=false
}

function createReview(config: {
  criteria: string;    // What to evaluate
  artifact: string;    // Text content OR screenshot path
  intelligence?: "fast" | "smart";
}): Promise<ReviewResult>;

Multimodal support: Both intelligence levels use multimodal models (text + vision). Artifact type detection is automatic:

• Text evaluation: artifact: "Your content here" → Routes as text input
• Vision evaluation: artifact: "./tmp/screenshot.png" → Routes as vision input (detects .png, .jpg, .jpeg extensions)

Intelligence levels (quality of judgment, not capability type):

• fast (default): Quick, cost-effective models for straightforward evaluations (e.g., Gemini 3.0 Flash)
• smart: Higher-quality models for nuanced aesthetic/creative judgment (e.g., GPT 5.1)

The fixture implementation selects appropriate models. (Examples are current options, not requirements.)

llm-review.test.ts - Shows Ralph how to use it (text and vision examples):

import { createReview } from "@/lib/llm-review";

// Example 1: Text evaluation
test("welcome message tone", async () => {
  const message = generateWelcomeMessage();
  const result = await createReview({
    criteria: "Message uses warm, conversational tone appropriate for design professionals while clearly conveying value proposition",
    artifact: message, // Text content
  });
  expect(result.pass).toBe(true);
});

// Example 2: Vision evaluation (screenshot path)
test("dashboard visual hierarchy", async () => {
  await page.screenshot({ path: "./tmp/dashboard.png" });
  const result = await createReview({
    criteria: "Layout demonstrates clear visual hierarchy with obvious primary action",
    artifact: "./tmp/dashboard.png", // Screenshot path
  });
  expect(result.pass).toBe(true);
});

// Example 3: Smart intelligence for complex judgment
test("brand visual consistency", async () => {
  await page.screenshot({ path: "./tmp/homepage.png" });
  const result = await createReview({
    criteria: "Visual design maintains professional brand identity suitable for financial services while avoiding corporate sterility",
    artifact: "./tmp/homepage.png",
    intelligence: "smart", // Complex aesthetic judgment
  });
  expect(result.pass).toBe(true);
});

Ralph learns from these examples: Both text and screenshots work as artifacts. Choose based on what needs evaluation. The fixture handles the rest internally.

Future extensibility: Current design uses single artifact: string for simplicity. Can expand to artifact: string | string[] if clear patterns emerge requiring multiple artifacts (before/after comparisons, consistency across items, multi-perspective evaluation). Composite screenshots or concatenated text could handle most multi-item needs.

Integration with Ralph Workflow

Planning Phase - Update PROMPT_plan.md:

After "...Study @IMPLEMENTATION_PLAN.md to determine starting point for research and keep it up to date with items considered complete/incomplete using subagents." insert:

When deriving test requirements from acceptance criteria, identify whether verification requires programmatic validation (measurable, inspectable) or human-like judgment (perceptual quality, tone, aesthetics). Both types are equally valid backpressure mechanisms. For subjective criteria that resist programmatic validation, explore src/lib for non-deterministic evaluation patterns.

Building Phase - Update PROMPT_build.md:

Prepend new guardrail (in the 9s sequence):

9999. Create tests to verify implementation meets acceptance criteria and include both conventional tests (behavior, performance, correctness) and perceptual quality tests (for subjective criteria, see src/lib patterns).

Discovery, not documentation: Ralph learns LLM review patterns from llm-review.test.ts examples during src/lib exploration (Phase 0c). No AGENTS.md updates needed - the code examples are the documentation.

Compatibility with Core Philosophy

The Critical Principle: Geoff's Ralph works from a single, disposable plan where Ralph picks "most important." To use branches with Ralph while maintaining this pattern, you must scope at plan creation, not at task selection.

• ❌   Wrong Approach: Create full plan, then ask Ralph to "filter" tasks at runtime → unreliable (70-80%), violates determinism
• ✓  Right Approach: Create a scoped plan upfront for each work branch → deterministic, simple, maintains "plan is disposable"

Solution: Add a plan-work mode to create a work-scoped IMPLEMENTATION_PLAN.md on the current branch. User creates work branch, then runs plan-work with a natural language description of the work focus. The LLM uses this description to scope the plan. Post planning, Ralph builds from this already-scoped plan with zero semantic filtering – just picks "most important" as always.

"Work" is intentionally a broad term – it can describe features, topics of concern, refactoring efforts, infrastructure changes, bug fixes, or any coherent body of related changes. The work description you pass to plan-work is natural language for the LLM – it can be prose, not constrained by git branch naming rules.

Design Principles

• ✅ Each Ralph session operates monolithically on ONE body of work per branch
• ✅ User creates branches manually - full control over naming conventions and strategy (e.g. worktrees)
• ✅ Natural language work descriptions - pass prose to LLM, unconstrained by git naming rules
• ✅ Scoping at plan creation (deterministic) not task selection (probabilistic)
• ✅ Single plan per branch - one IMPLEMENTATION_PLAN.md per branch
• ✅ Plan remains disposable - regenerate scoped plan when wrong/stale for a branch
• ✅ No dynamic branch switching within a loop session
• ✅ Maintains simplicity and determinism
• ✅ Optional - main branch workflow still works
• ✅ No semantic filtering at build time - Ralph just picks "most important"

Workflow:

1. Full Planning (on main branch)

   bash Copy

   ./loop.sh plan
   # Generate full IMPLEMENTATION_PLAN.md for entire project

2. Create Work Branch

   User performs:

   bash Copy

   git checkout -b ralph/user-auth-oauth
   # Create branch with whatever naming convention you prefer
   # Suggestion: ralph/* prefix for work branches

3. Scoped Planning (on work branch)

   bash Copy

   ./loop.sh plan-work "user authentication system with OAuth and session management"
   # Pass natural language description - LLM uses this to scope the plan
   # Creates focused IMPLEMENTATION_PLAN.md with only tasks for this work

4. Build from Plan (on work branch)

   bash Copy

   ./loop.sh
   # Ralph builds from scoped plan (no filtering needed)
   # Picks most important task from already-scoped plan

5. PR Creation (when work complete)

   User performs:

   bash Copy

   gh pr create --base main --head ralph/user-auth --fill

Work-Scoped loop.sh

Extends the base enhanced loop script to add work branch support with scoped planning:

#!/bin/bash
set -euo pipefail

# Usage:
#   ./loop.sh [plan] [max_iterations]       # Plan/build on current branch
#   ./loop.sh plan-work "work description"  # Create scoped plan on current branch

# Parse arguments
MODE="build"
PROMPT_FILE="PROMPT_build.md"

if [ "$1" = "plan" ]; then
    MODE="plan"
    PROMPT_FILE="PROMPT_plan.md"
    MAX_ITERATIONS=${2:-0}
elif [ "$1" = "plan-work" ]; then
    if [ -z "$2" ]; then
        echo "Error: plan-work requires a work description"
        exit 1
    fi
    MODE="plan-work"
    WORK_DESCRIPTION="$2"
    PROMPT_FILE="PROMPT_plan_work.md"
    MAX_ITERATIONS=${3:-5}
elif [[ "$1" =~ ^[0-9]+$ ]]; then
    MAX_ITERATIONS=$1
else
    MAX_ITERATIONS=0
fi

# ... (see README for full script)

PROMPT_plan_work.md Template

Note: Identical to PROMPT_plan.md but with scoping instructions and WORK_SCOPE env var substituted (automatically by the loop script).

0a. Study `specs/*` with up to 250 parallel Sonnet subagents to learn the application specifications.
0b. Study @IMPLEMENTATION_PLAN.md (if present) to understand the plan so far.
0c. Study `src/lib/*` with up to 250 parallel Sonnet subagents to understand shared utilities & components.
0d. For reference, the application source code is in `src/*`.

1. You are creating a SCOPED implementation plan for work: "${WORK_SCOPE}". Study @IMPLEMENTATION_PLAN.md (if present; it may be incorrect) and use up to 500 Sonnet subagents to study existing source code in `src/*` and compare it against `specs/*`. Use an Opus subagent to analyze findings, prioritize tasks, and create/update @IMPLEMENTATION_PLAN.md as a bullet point list sorted in priority of items yet to be implemented. Ultrathink. Consider searching for TODO, minimal implementations, placeholders, skipped/flaky tests, and inconsistent patterns. Study @IMPLEMENTATION_PLAN.md to determine starting point for research and keep it up to date with items considered complete/incomplete using subagents.

IMPORTANT: This is SCOPED PLANNING for "${WORK_SCOPE}" only. Create a plan containing ONLY tasks directly related to this work scope. Be conservative - if uncertain whether a task belongs to this work, exclude it. The plan can be regenerated if too narrow. Plan only. Do NOT implement anything. Do NOT assume functionality is missing; confirm with code search first. Treat `src/lib` as the project's standard library for shared utilities and components. Prefer consolidated, idiomatic implementations there over ad-hoc copies.

ULTIMATE GOAL: We want to achieve the scoped work "${WORK_SCOPE}". Consider missing elements related to this work and plan accordingly. If an element is missing, search first to confirm it doesn't exist, then if needed author the specification at specs/FILENAME.md. If you create a new element then document the plan to implement it in @IMPLEMENTATION_PLAN.md using a subagent.

Compatibility with Core Philosophy

Topics of Concern → Activities

Geoff's suggested workflow already aligns planning with Jobs-to-be-Done – breaking JTBDs into topics of concern, which in turn become specs. I think there's an opportunity to lean further into the product benefits this approach affords by reframing topics of concern as activities.

Activities are verbs in a journey ("upload photo", "extract colors") rather than capabilities ("color extraction system"). They're naturally scoped by user intent.

Topics: "color extraction", "layout engine" → capability-oriented

Activities: "upload photo", "see extracted colors", "arrange layout" → journey-oriented

Activities → User Journey

Activities – and their constituent steps – sequence naturally into a user flow, creating a journey structure that makes gaps and dependencies visible. A User Story Map organizes activities as columns (the journey backbone) with capability depths as rows – the full space of what could be built:

UPLOAD    →   EXTRACT    →   ARRANGE     →   SHARE

basic         auto           manual          export
bulk          palette        templates       collab
batch         AI themes      auto-layout     embed

User Journey → Release Slices

Horizontal slices through the map become candidate releases. Not every activity needs new capability in every release — some cells stay empty, and that's fine if the slice is still coherent:

              UPLOAD    →   EXTRACT    →   ARRANGE     →   SHARE

Release 1:    basic         auto                           export
              ───────────────────────────────────────────────────
Release 2:                  palette        manual
              ───────────────────────────────────────────────────
Release 3:    batch         AI themes      templates       embed

Release Slices → SLC Releases

The story map gives you structure for slicing. Jason Cohen's Simple, Lovable, Complete (SLC) gives you criteria for what makes a slice good:

• Simple – Narrow scope you can ship fast. Not every activity, not every depth.
• Complete – Fully accomplishes a job within that scope. Not a broken preview.
• Lovable – People actually want to use it. Delightful within its boundaries.

Why SLC over MVP? MVPs optimize for learning at the customer's expense – "minimum" often means broken or frustrating. SLC flips this: learn in-market while delivering real value. If it succeeds, you have optionality. If it fails, you still treated users well.

Each slice can become a release with a clear value and identity:

                 UPLOAD  →   EXTRACT    →   ARRANGE     →   SHARE

Palette Picker:  basic       auto                           export
                 ───────────────────────────────────────────────────
Mood Board:                  palette        manual
                ───────────────────────────────────────────────────
Design Studio:   batch       AI themes      templates       embed

• Palette Picker – Upload, extract, export. Instant value from day one.
• Mood Board – Adds arrangement. Creative expression enters the journey.
• Design Studio – Professional features: batch processing, AI themes, embeddable output.

Operationalizing with Ralph

The concepts above – activities, story maps, SLC releases – are the thinking tools. How do we translate them into Ralph's workflow?

Default Ralph approach:

1. Define Requirements: Human + LLM define JTBD topics of concern → specs/*.md
2. Create Tasks Plan: LLM analyzes all specs + current code → IMPLEMENTATION_PLAN.md
3. Build: Ralph builds against full scope

This works well for capability-focused work (features, refactors, infrastructure). But it doesn't naturally produce valuable (SLC) product releases – it produces "whatever the specs describe".

Activities → SLC Release approach:

To get SLC releases, we need to ground activities in audience context. Audience defines WHO has the JTBDs, which in turn informs WHAT activities matter and what "lovable" means.

Audience (who)
    └── has JTBDs (why)
            └── fulfilled by Activities (how)

Workflow

I. Requirements Phase (2 steps):

Still performed in LLM conversations with the human, similar to the default Ralph approach.

1. Define audience and their JTBDs – WHO are we building for and what OUTCOMES do they want?
   • Human + LLM discuss and determine the audience(s) and their JTBDs (outcomes they want)
   • May contain multiple connected audiences (e.g. "designer" creates, "client" reviews)
   • Generates AUDIENCE_JTBD.md
2. Define activities – WHAT do users do to accomplish their JTBDs?
   • Informed by AUDIENCE_JTBD.md
   • For each JTBD, identify activities necessary to accomplish it
   • For each activity, determine:
     • Capability depths (basic → enhanced) – levels of sophistication
     • Desired outcome(s) at each depth – what does success look like?
   • Generates specs/*.md (one per activity)

The discrete steps within activities are implicit and LLM can infer them during planning.

II. Planning Phase:

Performed in Ralph loop with updated planning prompt.

• LLM analyzes:
  • AUDIENCE_JTBD.md (who, desired outcomes)
  • specs/* (what could be built)
  • Current code state (what exists)
• LLM determines next SLC slice (which activities, at what capability depths) and plans tasks for that slice
• LLM generates IMPLEMENTATION_PLAN.md
• Human verifies plan before building:
  • Does the scope represent a coherent SLC release?
  • Are the right activities included at the right depths?
  • If wrong → re-run planning loop to regenerate plan, optionally updating inputs or planning prompt
  • If right → proceed to building

III. Building Phase: Performed in Ralph loop with standard building prompt.

Updated PROMPT_plan_slc.md Template

Variant of PROMPT_plan.md that adds audience context and SLC-oriented slice recommendation.

Notes:

• Unlike the default template, this does not have a [project-specific goal] placeholder – the goal is implicit: recommend the most valuable next release for the audience.
• Current subagents names presume using Claude.

0a. Study @AUDIENCE_JTBD.md to understand who we're building for and their Jobs to Be Done.
0b. Study `specs/*` with up to 250 parallel Sonnet subagents to learn JTBD activities.
0c. Study @IMPLEMENTATION_PLAN.md (if present) to understand the plan so far.
0d. Study `src/lib/*` with up to 250 parallel Sonnet subagents to understand shared utilities & components.
0e. For reference, the application source code is in `src/*`.

1. Sequence the activities in `specs/*` into a user journey map for the audience in @AUDIENCE_JTBD.md. Consider how activities flow into each other and what dependencies exist.

2. Determine the next SLC release. Use up to 500 Sonnet subagents to compare `src/*` against `specs/*`. Use an Opus subagent to analyze findings. Ultrathink. Given what's already implemented recommend which activities (at what capability depths) form the most valuable next release. Prefer thin horizontal slices - the narrowest scope that still delivers real value. A good slice is Simple (narrow, achievable), Lovable (people want to use it), and Complete (fully accomplishes a meaningful job, not a broken preview).

3. Use an Opus subagent (ultrathink) to analyze and synthesize the findings, prioritize tasks, and create/update @IMPLEMENTATION_PLAN.md as a bullet point list sorted in priority of items yet to be implemented for the recommended SLC release. Begin plan with a summary of the recommended SLC release (what's included and why), then list prioritized tasks for that scope. Consider TODOs, placeholders, minimal implementations, skipped tests - but scoped to the release. Note discoveries outside scope as future work.

IMPORTANT: Plan only. Do NOT implement anything. Do NOT assume functionality is missing; confirm with code search first. Treat `src/lib` as the project's standard library for shared utilities and components. Prefer consolidated, idiomatic implementations there over ad-hoc copies.

ULTIMATE GOAL: We want to achieve the most valuable next release for the audience in @AUDIENCE_JTBD.md. Consider missing elements and plan accordingly. If an element is missing, search first to confirm it doesn't exist, then if needed author the specification at specs/FILENAME.md. If you create a new element then document the plan to implement it in @IMPLEMENTATION_PLAN.md using a subagent.

Notes

Why AUDIENCE_JTBD.md as a separate artifact:

• Single source of truth – prevents drift across specs
• Enables holistic reasoning: "What does this audience need MOST?"
• JTBDs captured alongside audience (the "why" lives with the "who")
• Referenced twice: during spec creation AND SLC planning
• Keeps activity specs focused on WHAT, not repeating WHO

Cardinalities:

• One audience → many JTBDs ("Designer" has "capture space", "explore concepts", "present to client")
• One JTBD → many activities ("capture space" includes upload, measurements, room detection)
• One activity → can serve multiple JTBDs ("upload photo" serves both "capture" and "gather inspiration")