ezos26/claude-skills/ralph-dry-run

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

# 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"}

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}

## 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]

{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]

{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]

{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]

{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]