Ralph dry run

Ralph Dry Run — Interpretation Validation

Tabletop exercise for PRDs. Agents simulate implementing the plan against the real codebase — reading actual files, tracing actual paths — without writing code. They find every point where the PRD's assumptions don't match reality, then produce an amended PRD ready for execution.

When to Use

• After writing a PRD, before running /ralph2
• After /ralph-planning-audit passes structural validation
• When a PRD touches many existing files and you're not sure it accounts for all the wiring
• When onboarding to someone else's PRD

Pipeline Position

/ralph-planning-audit  →  structural validation (schema, deps, collisions)
/ralph-dry-run         →  interpretation validation (code reality check) → PRD v2
/ralph2                →  execution from PRD v2

Trigger Phrases

• /ralph-dry-run
• /ralph-dry-run [prd-path]
• /dry-run
• "dry run the PRD"
• "simulate the implementation"

Input Detection

Parse user input for:

• PRD path: explicit path, or auto-detect by globbing docs/**/*PRD*, docs/**/*prd*, **/*plan*PRD*
• Codebase map: if .ralph/codebase-map.md exists (from a prior /ralph2 Stage 0), reuse it

If no PRD found, ask the user.

---

Stage 0: Ground Truth

Before agents simulate anything, build a verified map of the codebase.

0A: Read Project Context

Read these files (skip if missing):

1. CLAUDE.md — project constraints, dev commands
2. AGENTS.md — patterns, conventions, tech stack
3. package.json — dependencies, scripts
4. The PRD file — full implementation plan
5. frontend-api-contract.md or equivalent — API contract
6. Any handoff doc referenced by the PRD

Construct a {context block} containing:

• Tech stack, project structure, key conventions
• Isolation rules, auth patterns, deployment constraints
• API contract summary
• Full PRD contents

0B: Codebase Scanner

If .ralph/codebase-map.md exists and is recent, reuse it. Otherwise generate it.

For every file referenced in the PRD:

1. Verify it exists (glob for it)
2. Read it — note key exports, function signatures, important line numbers
3. Flag discrepancies: file moved, function renamed, structure different than PRD assumes

Write to .ralph/codebase-map.md:

# Codebase Map
Generated: {date}
PRD: {path}

## Files Referenced in PRD
| File | Exists | Key Exports / Relevant Code |
|------|--------|----------------------------|
| {path} | YES/NO | {exports, key functions, line numbers} |

## Discrepancies
- {PRD says X but code shows Y}

## Quality Gate Commands
- Typecheck: {command}
- Lint: {command or "none"}
- Test: {command or "none"}

0C: Extract Simulation Targets

From the PRD, extract a structured list of every change:

Phase {N}: {title}
  Modify: {file} — {what the PRD says to change}
  Modify: {file} — {what the PRD says to change}
  Create: {file} — {what the PRD says to create}

This list feeds into all 4 agents. It ensures they trace the same set of changes.

---

Stage 1: Simulation Agents (4, parallel, read-only)

Launch ALL 4 agents simultaneously using run_in_background: true. All use subagent_type: "Explore". All are strictly read-only — they do NOT write code or modify files.

Every agent receives:

• The full context block (Stage 0A)
• The codebase map (Stage 0B)
• The simulation targets list (Stage 0C)
• The Agent Roster (so they can flag cross-cutting concerns)

## Agent Roster (you are Agent {N})
1. Data Tracer — traces every data field from origin to consumer
2. Execution Tracer — traces runtime paths step by step
3. Boundary Checker — checks API contracts, auth, isolation, external services
4. Step Completeness Checker — decomposes PRD instructions into actual code changes

If you find something outside your domain, note it as:
  CROSS-REF [Agent N]: [what they should check]

---

Agent 1: Data Tracer

"Where does every piece of data come from, and where does it go?"

{context block}
{codebase map}
{simulation targets}
{agent roster}

## Your Focus: Data Flow Tracing (READ ONLY — do NOT modify any files)

For each new field, column, or data structure the PRD introduces:

1. **Trace upstream**: Where does this data originate?
   - User input? AI output? Computed? Stripe metadata?
   - Read the actual code where it would be created

2. **Trace downstream**: What consumes this data?
   - API responses? PDF sections? Emails? Frontend?
   - Read the actual consumer code to verify it can receive the data

3. **Check transformations**: Does the data change shape between layers?
   - snake_case in DB, camelCase in API?
   - Different field names in different layers?
   - Read the actual serialization/query code

4. **Flag orphans**:
   - Data written but never read
   - Data expected by a consumer but never produced
   - Fields in the PRD output schema that no code populates

5. **Produce hypothetical diffs**: For each gap, show the specific code change needed:

// file:line

• the line that would need to be added

## OUTPUT FORMAT (MANDATORY)
DATA TRACE REPORT
=================
Fields Traced: {count}

Per Field:
FIELD: {name}
Origin: {where it comes from} — {file:line}
Storage: {where it's stored} — {file:line}
Consumers:
 - {consumer} — {file:line} — {CONNECTED / GAP: description}
Transformations: {shape changes between layers}
Hypothetical Diff (if gap found):
 ```
 // {file:line}
 + {what needs adding}
 ```

Orphan Fields:
- {field}: {written at file:line, never read} or {expected at file:line, never produced}

CROSS-REF:
- [Agent N]: [what they should check]

---

Agent 2: Execution Tracer

"If a user clicked 'Buy Now' right now, what happens at every step?"

{context block}
{codebase map}
{simulation targets}
{agent roster}

## Your Focus: Runtime Path Tracing (READ ONLY — do NOT modify any files)

For each phase, pick the primary user action (checkout, submit domains, view results)
and trace the ACTUAL runtime path through the code, function by function.

1. **Start at the entry point**: HTTP route, webhook handler, Trigger.dev task
   - Read the actual handler code
   - Note the exact line numbers

2. **Follow every function call**:
   - What validates the input? (Zod schemas, middleware)
   - What transforms the data?
   - What stores the data?
   - What dispatches to the next step?

3. **At each branching point**, check:
   - Does the PRD account for this branch?
   - Would the new product_type / tier take the right path?
   - Is there validation or middleware that would strip/reject the new data?

4. **Check function signatures**: If the PRD says "add parameter X to function Y":
   - Read function Y — what's its current signature?
   - Find ALL callers of function Y — do they all need updating?
   - Does the PRD mention updating the callers?

5. **Produce hypothetical diffs**: For each issue, show the specific change:

// file:line — current

• functionName(orderId, email)

• functionName(orderId, email, productType)

## OUTPUT FORMAT (MANDATORY)
EXECUTION TRACE REPORT
======================
Paths Traced: {count}

Per Path:
PATH: {user action} → {endpoint}

Step 1: {description}
 Code: {file:line}
 Current behavior: {what happens now}
 PRD expects: {what the PRD says should happen}
 Status: OK / ISSUE
 {if ISSUE: description + hypothetical diff}

Step 2: ...

Function Signature Changes Required:
- {function} at {file:line}: {current sig} → {needed sig}
 Callers that need updating: {list with file:line}
 PRD covers this: YES / NO

CROSS-REF:
- [Agent N]: [what they should check]

---

Agent 3: Boundary Checker

"What breaks at system edges?"

{context block}
{codebase map}
{simulation targets}
{agent roster}

## Your Focus: System Boundary Verification (READ ONLY — do NOT modify any files)

1. **API Contract Compliance**:
   - Read frontend-api-contract.md (or equivalent)
   - For every PRD change that touches an API endpoint:
     - Does the change preserve the existing contract?
     - Does the PRD update the contract doc?
     - Would existing frontend code break?
   - Check response shapes, field names (snake_case), status codes

2. **Worker Isolation**:
   - For every change to worker/src/: verify no imports from src/lib/
   - Check that duplicated values (tier prices, config) stay in sync
   - Verify the Worker can access everything it needs via bindings/env

3. **Auth & Cookie Paths**:
   - Read auth/cookie code — what paths are cookies set on?
   - Will new route prefixes receive auth cookies?
   - Does the auth parsing code recognize new path prefixes?

4. **External Service Compatibility**:
   - Stripe: metadata limits, webhook signature handling
   - Langfuse: prompt names, model config
   - Postmark: email template compatibility
   - R2: storage path conventions
   - Trigger.dev: task registration, machine types

5. **Backward Compatibility**:
   - Existing orders/data: affected by schema changes?
   - Migration handles existing rows?
   - Default values prevent null errors on old data?

## OUTPUT FORMAT (MANDATORY)
BOUNDARY CHECK REPORT
=====================
Boundaries Checked: {count}

API Contract:
  - {endpoint}: {PRESERVED / AT RISK: description}
  Hypothetical diff for contract doc:
    ```
    + {what to add to frontend-api-contract.md}
    ```

Worker Isolation:
  - {check}: {PASS / VIOLATION: description}

Auth:
  - Cookie path: {WORKS / ISSUE: description}
  - Auth parsing: {WORKS / ISSUE: description}

External Services:
  - {service}: {COMPATIBLE / ISSUE: description}

Backward Compatibility:
  - {concern}: {SAFE / RISK: description}

CROSS-REF:
  - [Agent N]: [what they should check]

---

Agent 4: Step Completeness Checker

"Does the PRD list every code change actually required?"

{context block}
{codebase map}
{simulation targets}
{agent roster}

## Your Focus: Step Completeness (READ ONLY — do NOT modify any files)

For EVERY instruction in the PRD, decompose it into the actual atomic code changes required. Then check if the PRD mentions all of them.

Example:
  PRD says: "Add product_type column to reportOrders"
  Actual steps required:
    1. Add column definition in schema.ts
    2. Run drizzle-kit generate
    3. Run migration
    4. Update all INSERT queries that write to reportOrders
    5. Update all SELECT queries that read from reportOrders (if needed)
    6. Update TypeScript types/interfaces that reference the table
    7. Update any Zod schemas that validate order data
  PRD covers: 1, 2, 3
  PRD misses: 4, 5, 6, 7

For each phase:

1. **Read every PRD instruction**
2. **Read the actual code it references**
3. **List ALL atomic changes needed** to make that instruction work
4. **Diff against what the PRD says** — flag missing steps
5. **Check ripple effects**: if file A changes, what other files must change?
   - Importers of changed exports
   - Callers of changed functions
   - Templates that reference changed data
   - Tests that exercise changed code

## OUTPUT FORMAT (MANDATORY)
STEP COMPLETENESS REPORT
========================
Instructions Analyzed: {count}
Complete: {count}
Incomplete: {count}

Per Phase:
  PHASE {N}: {title}

  Instruction: "{PRD instruction text}"
    Required steps:
      1. {step} — PRD: COVERED / MISSING
      2. {step} — PRD: COVERED / MISSING
      3. {step} — PRD: COVERED / MISSING

    Ripple effects:
      - {file}: {what needs changing} — PRD: COVERED / MISSING

  Instruction: "{next instruction}"
    ...

Missing Steps Summary (grouped by phase):
  Phase {N}:
    - {missing step description} — affects {file:line}
    - {missing step description} — affects {file:line}

CROSS-REF:
  - [Agent N]: [what they should check]

---

Stage 2: Cross-Examination

After all 4 agents complete:

1. Collect all reports
2. Extract CROSS-REF items — questions agents have for each other
3. Find overlaps — same file/function flagged by 2+ agents
4. Find contradictions — agents disagree about whether something works

For each substantive cross-ref, overlap, or contradiction, launch a targeted arbitration agent:

subagent_type: "Explore"
run_in_background: true

Arbitration prompt:

{context block}

## Arbitration Task

Agent {A} ({role}) says:
  {their finding, with file paths and reasoning}

Agent {B} ({role}) says:
  {their finding, or the cross-ref question}

{If other agents commented on the same area, include their observations}

Your job:
1. Read the actual code at the referenced file:line locations
2. Determine who is correct
3. If both are partially right, explain why

## OUTPUT FORMAT (MANDATORY)
ARBITRATION RESULT
==================
Topic: {what's being disputed}
Agent {A} ({role}): {CONFIRMED / REFUTED / PARTIALLY RIGHT}
Agent {B} ({role}): {CONFIRMED / REFUTED / PARTIALLY RIGHT}
Evidence: {what the code actually shows, with file:line}
Conclusion: {the ground truth}
PRD Impact: {what needs changing in the PRD, if anything}

Guidelines:

• Only arbitrate HIGH-impact items: critical gaps, contradictions, explicit CROSS-REFs
• Batch related items touching the same files into a single arbitrator
• Limit to ~3 arbitration agents max
• Skip if no substantive conflicts

---

Stage 3: Synthesis — Dry Run Report + PRD v2

After all agents (including arbitrators) complete, build two outputs.

Output 1: Dry Run Report

Write to .ralph/dry-run-report.md:

# Dry Run Report — {PRD Name}
Date: {date}
PRD: {path}
Agents: Data Tracer, Execution Tracer, Boundary Checker, Step Completeness Checker

## Confidence by Phase
Phase 1: {HIGH/MEDIUM/LOW} — {one-line reason}
Phase 2: {HIGH/MEDIUM/LOW} — {one-line reason}
...

## Critical Gaps (must fix before execution)

### GAP-001: {title}
Phase: {N}
Found by: {agent} {confirmed by cross-exam if applicable}
Issue: {description}
Code evidence: {file:line — what the code actually shows}
Hypothetical diff:

// {file:line}

• {what needs adding/changing}

PRD amendment: {exact text to add/change in the PRD}

### GAP-002: ...

## Important Gaps (should fix, lower risk)
### GAP-{N}: ...

## Observations (no action needed)
### OBS-{N}: ...

## Missing Steps (from Step Completeness Checker)
Phase {N}:
- {step}: {what's missing}
Phase {N}:
- {step}: {what's missing}

## Cross-Exam Results
- {topic}: {conclusion}

## Suggested Phase Order Changes
{If the dry run revealed a better ordering, suggest it. Otherwise: "No changes needed."}

Output 2: PRD v2

This is the key deliverable. Create an amended copy of the PRD:

1. Copy the original PRD to .ralph/prd-v2.md (or {original-name}-v2.md next to the original)
2. Apply all Critical Gap amendments directly into the text
3. Apply all Missing Steps — add them to the appropriate phase
4. Add all Important Gap amendments with a [DRY-RUN] prefix so the user can review
5. Add a changelog section at the top:

## Dry Run Amendments
Applied: {date}
Gaps found: {critical count} critical, {important count} important, {obs count} observations

Changes made:
- GAP-001: {one-line description of amendment}
- GAP-002: {one-line description of amendment}
- STEP: Added {N} missing steps across {M} phases
- [DRY-RUN] GAP-003: {flagged for user review}

Present to User

Ralph Dry Run Complete
======================
PRD: {path}
Confidence: Phase 1 {H/M/L} | Phase 2 {H/M/L} | Phase 3 {H/M/L} | ...

Gaps: {critical} critical, {important} important, {obs} observations
Missing steps: {count} across {phases} phases
Cross-exam: {count} arbitrated, {count} confirmed

PRD v2: .ralph/prd-v2.md (all critical gaps + missing steps applied)
Full report: .ralph/dry-run-report.md

Review PRD v2, then run: /ralph2 .ralph/prd-v2.md

---

Key Principles

1. Simulate, don't audit — agents pretend to implement, tracing real code paths. They don't check style or patterns — they check "would this actually work?"
2. Read real code, not assumptions — every claim must reference a file:line. No "the schema probably has..." — read the schema.
3. Hypothetical diffs force precision — "add product_type to the select" is vague. + product_type: reportOutputs.liquidity_analysis at worker/src/index.ts:1852 is verifiable.
4. Four orthogonal perspectives — data, execution, boundaries, completeness. Each catches different classes of interpretation bugs.
5. Arbitrate, don't debate — when agents disagree, a targeted agent reads the code and determines ground truth. No open-ended discussion.
6. The output is a better PRD — not just a report. The amended PRD v2 is the deliverable that feeds directly into /ralph2.
7. Cheaper than one failed phase — 4-7 read-only agents costs less than a failed worker + audit + fix + verify cycle.