plan-to-ralph

name	plan-to-ralph
description	Interactive Q&A to generate ralph-o-matic review files (RALPH.md, focus-areas.md, gaps-identified.md) customized for your project

Plan to Ralph

You are generating ralph-o-matic review files through interactive Q&A. This skill produces three files that configure a ralph refinement run:

• RALPH.md — Review instructions (persona, mission, steps, checklist, promise tags)
• docs/reference/focus-areas.md — Review tracking table (single areas with 2 passes, paired areas with 1 pass)
• docs/reference/gaps-identified.md — Issue tracker (open, fixed, won't-fix sections)

After generating these files, the user runs /direct-to-ralph or ralph-o-matic submit to start the review.

Arguments

Parse the following from the user's command:

• CONTEXT (optional): Free-text description of what the review should focus on (e.g., "on the work on the new identity system"). When provided, narrows codebase scan and pre-seeds Q&A answers.
• --reset: Skip backup. Overwrite existing files without creating historical copies.

Prerequisites

Before starting, verify:

git rev-parse --is-inside-work-tree

If this fails, stop and tell the user: "This skill requires a git repository. Initialize one with git init first."

---

Phase 1: Backup

Skip this phase if --reset was passed.

Check if any of these files exist:

• RALPH.md
• docs/reference/focus-areas.md
• docs/reference/gaps-identified.md

If none exist: Skip silently to Phase 2.

If any exist: Archive them before regenerating.

1. Create docs/reference/historical/ if it doesn't exist.
2. Get today's date as YYYY-MM-DD.
3. For each existing file, move (rename) it into docs/reference/historical/ with the naming pattern — do NOT copy it. The original must no longer exist at its working-tree location afterward:
   • RALPH.md → YYYY-MM-DD-historical-RALPH.md
   • focus-areas.md → YYYY-MM-DD-historical-focus-areas.md
   • gaps-identified.md → YYYY-MM-DD-historical-gaps-identified.md
4. If a same-day backup already exists, append a counter: -2, -3, etc. For example, if 2026-03-12-historical-RALPH.md already exists, use 2026-03-12-historical-RALPH-2.md.
5. Tell the user what was archived: "Archived existing files to docs/reference/historical/."

Why move instead of copy: Phase 4 regenerates each file fresh from the template in this skill, which carries the required control semantics — notably the <promise> tag logic that lets the ralph server stop after repeated "no progress" iterations. If the old files stayed in place, a previously mangled RALPH.md (one whose <promise> logic was stripped by an earlier run) could survive or be only partially rewritten instead of fully regenerated. Moving the originals out guarantees these files are absent when Phase 4 runs, so the fresh template — with its control semantics intact — is always what gets written. This also subsumes the old legacy-format migration: any legacy or mangled RALPH.md is archived and replaced wholesale.

---

Phase 2: Scan

Use the Agent tool with subagent_type: "Explore" to discover codebase structure. Send the subagent this prompt:

Explore this codebase and report back a structured inventory. I need:

1. Project type — What language(s), framework(s), build system(s)? Look for: go.mod, package.json, pyproject.toml, Cargo.toml, *.csproj, *.sln, Makefile, CMakeLists.txt, etc.

2. Components — Group files by directory/module. For each component, report:

   • Name (directory name or module name)
   • Key files (entry points, main logic files)
   • One-line description of what it does

   Look in these standard locations: src/, internal/, lib/, cmd/, app/, packages/, pkg/, modules/, and top-level directories that contain source code.

3. Entry points — Files like main.go, main.py, index.ts, Program.cs, app.py, server.ts, Dockerfile

4. Config/infra — CI/CD workflows (.github/workflows/), docker files, migration directories, config directories

5. Test directories — Map test files/directories back to the components they test. Look for: tests/, test/, test.go, *.test.ts, test.py, *.spec.ts, *_test.py

6. Design docs or specs — Any files in docs/plans/, docs/specs/, docs/designs/, docs/reference/ that describe the system

{IF CONTEXT WAS PROVIDED: "7. Context focus — The user wants to focus on: '{CONTEXT}'. Identify which components are directly related to this context, and which components touch those (same package, co-located files, shared config, related tests). Mark each component as 'direct' or 'indirect'."}

Return the results as a structured list grouped by category.

Store the scan results for use in Phase 3.

If the scan finds zero components (empty repo or no source code), note this — you'll ask the user to define focus areas manually in Phase 3.

Record the branch-point test baseline

Before any refinement runs, capture which tests already fail right now, so the loop can gate on NEW-vs-baseline rather than demanding a fully green suite. The repo MAY be red on arrival — that is fine; pre-existing failures are not this review's job.

1. Run the project's test command (the one you'll confirm as TEST_COMMAND in Phase 3 — auto-detect it now if needed). For a mixed-language repo, run each suite.
2. For each suite, capture: whether it built/compiled at all, the pass/fail counts, and the stable identifier of each failing test (fully-qualified name or file > test, no timestamps/durations).
3. Write the result to docs/reference/test-baseline.md as a simple, human-readable record — per suite: the exact command, build-ok status, pass/fail counts, and the list of pre-existing failing test ids. If a suite fails to build, note BUILD FAILED with a one-line error summary instead of a test list. If you genuinely find no test suite, write the file noting that and move on.

Store the recorded failing set as BASELINE_FAILURES (and the build status per suite). The generated RALPH.md will gate "done" on no NEW failures vs this baseline — see Phase 4. Pre-existing failures are logged, not fixed, and must not block the loop.

---

Phase 3: Q&A

Ask questions one at a time. Skip questions that CONTEXT already answers.

Question 1: Mission

Skip if CONTEXT provides a clear description of what to review.

Ask: "What should this ralph review improve? Describe the feature, system, or area of code."

Store the answer as MISSION.

If CONTEXT was provided, use it as the MISSION and tell the user: "Based on your context, the review will focus on: {CONTEXT}. Sound right?" Accept corrections.

Question 2: Test Command

Auto-detect the test command by checking for:

• Makefile → look for test target (use make test)
• package.json → look for test script (use npm test)
• pyproject.toml → (use pytest tests/ -v)
• go.mod → (use go test ./...)
• Cargo.toml → (use cargo test)
• *.sln or *.csproj → (use dotnet test)

Present the detected command: "I detected {COMMAND} as your test command. Use this, or enter a different one?"

If nothing is detected, ask: "What command runs your tests? (e.g., make test, npm test, pytest)"

The test command is required. Store it as TEST_COMMAND.

Question 3: Persona

Generate a persona paragraph based on:

• The language/framework from the scan
• The MISSION description
• Any design docs found in the scan
• The architecture patterns visible in the codebase (e.g., hexagonal, MVC, microservices)

The persona should follow this pattern (drawn from real examples):

You are a [ROLE] who [RELEVANT EXPERTISE]. You understand [ARCHITECTURE/PATTERNS] and [DOMAIN KNOWLEDGE]. You care about [QUALITY ATTRIBUTES].

Present it and ask:

1. Accept — use this persona as-is
2. See alternatives — show 3 more persona suggestions (plus the original, so 4 total to choose from)
3. Write your own — type a custom persona

If they choose "See alternatives," generate 3 additional personas with different emphases (e.g., security-focused, test-coverage-focused, spec-alignment-focused, performance-focused) and present all 4 as a numbered list. They can pick a number or type their own.

Store the final persona as PERSONA.

Question 4: Single Focus Areas

If the scan found components:

Present the discovered components as a numbered list grouped by category:

Based on the codebase scan, here are the candidate focus areas:

**Core Components:**
  [1] Component A (src/component_a/) — handles user authentication
  [2] Component B (src/component_b/) — payment processing logic

**Supporting:**
  [3] Database Layer (src/db/) — schema, migrations, queries
  [4] Configuration (config/) — env loading, defaults

**Infrastructure:**
  [5] CI/CD (.github/workflows/) — build, test, deploy pipelines
  [6] Docker (Dockerfile, docker-compose.yml) — container config

**Test Coverage:**
  [7] Tests (tests/) — test isolation, mocking, coverage gaps

Which areas should be included in the review? You can:
- List numbers to include (e.g., "1, 2, 3, 5")
- Say "all" to include everything
- Add areas not in the list (e.g., "also add: API endpoints (src/api/)")
- Remove areas (e.g., "drop 6")

If the scan found zero components:

Ask: "I couldn't detect clear components in this codebase. Please describe the focus areas for review. List them one per line, with a brief description of what each covers."

For each selected/added focus area, ensure it has:

• A name
• Key files (from scan or user input)
• A one-line review scope description

Store the final list as SINGLE_AREAS.

Question 5: Paired Focus Areas

Generate suggested pairings from the selected single areas:

• Components that share a directory parent or have naming relationships
• When CONTEXT was provided: the context system paired with every component it touches (direct and indirect)
• Common integration seams: API + DB, client + server, config + all, tests + components

Present as a numbered list:

Suggested paired reviews (verifying integration seams):

  [1] Component A + Component B — data flow, error propagation
  [2] Component A + Database — query correctness, transaction boundaries
  [3] Config + All Components — env vars match behavior, defaults correct
  [4] Tests + Components — tests cover seams, not just happy paths

Which pairs to include? Same controls as above: list numbers, "all", add new pairs, or drop.

Store the final list as PAIRED_AREAS.

Question 6: Checklist

Present the proposed checklist:

Proposed review checklist (assessed each pass):

Universal (always included):
  [1] No NEW test failures vs the recorded branch-point baseline (`{TEST_COMMAND}`) — pre-existing failures excluded; nothing that built at baseline is now broken
  [2] Wired-and-fed: every new field/collaborator/config for this area is constructed at the REAL composition root and fed real data from an existing producer (verified by `grep -rn <Symbol>` — populated outside `*_test.go`), not nil/empty/hardcoded
  [3] No green-theater: ≥1 test for this area would fail if its production input were nil/empty; fakes don't ignore load-bearing args; "integration" tests assert the SINK
  [4] No open issues in `docs/reference/gaps-identified.md` for this focus area
  [5] The focus area is complete and polished — you'd be proud to ship it

Proposed (based on your project):
  [6] {proposed item based on context, e.g., "The code aligns with the design doc"}
  [7] {proposed item, e.g., "Module boundaries are clean — no adapter types in core"}

Add, remove, or edit items? Or accept as-is?

Generate 1-3 proposed items based on what you've learned:

• If a design doc exists → add spec alignment item
• If hexagonal/layered architecture detected → add boundary cleanliness item
• If security-related MISSION → add security-specific item
• If test framework detected with coverage tools → add test scenario categories item

Store the final checklist as CHECKLIST.

Question 7: Additional Constraints

Present the standard constraints that are always included:

These constraints are always included:
- No sub-agents for bulk generation
- Read before you write
- One focus area, one fix, one commit
- Don't invent new functionality (log gaps instead)

Any project-specific constraints to add? (e.g., "Do NOT write Python scripts for analysis", "Run linting after every change"). Enter to skip.

Store any additions as EXTRA_CONSTRAINTS.

---

Phase 4: Generate

Write all 3 files. Create docs/reference/ directory if it doesn't exist.

Generate RALPH.md

Write RALPH.md in the repository root with this structure (substitute all {VARIABLES} with values from Q&A):

# Review Instructions

You are an automated code reviewer. The user is unavailable — do the work without asking for input.

## Persona

{PERSONA}

## Your Mission

{MISSION_DESCRIPTION — expand the MISSION into 1-3 paragraphs describing what was built, what the review covers, and what "done" looks like}

## Tracking System

- Read `docs/reference/focus-areas.md` before starting. Each single area (from table 1) needs **2 review passes** before being considered __done__. Each paired area (from table 2) needs **1 review pass** before being considered __done__. Use this document to track which reviews have been advanced and completed.
- DO NOT update this document until the "Wrap Up" phase. Updating is conditional on your checklist assessment.

## Constraints

- **Do NOT use sub-agents for bulk generation.** When you modify or create code, do it by hand, one component at a time, with thought behind each decision.
- **Read before you write.** Before modifying any file, read the relevant sections. Before claiming something is fine, read it and reason about quality.
- **One focus area, one fix, one commit.** Pick a focus area. Find issues. Fix the ONE most important issue. Commit, push, and stop. Do not fix a second issue.
- **Do NOT invent new functionality to fill perceived gaps.** Maintain a list of things you find that should be fixed at `docs/reference/gaps-identified.md` in the `## Open Issues` section. If you perceive there is new, missing functionality beyond the current scope, log it in the `## Won't Fix (Beyond Current Scope)` section. If something on the list has been fixed previously, move it to `## Fixed Previously`.
{EXTRA_CONSTRAINTS — each as a new bullet point with bold lead, same format as above}

## Steps

1. **Read the Tracking File** — Read `docs/reference/focus-areas.md` and pick a review focus area that hasn't been completed yet. Complete single area reviews before moving to paired area reviews.
2. **Read the Area's Code** — Deeply examine the code for the chosen focus area. Read every file. Understand the patterns.
3. **Analyze findings and update the gaps list** — Cross-reference what you just read with the design doc and codebase conventions. Add any issues found to `docs/reference/gaps-identified.md` in the `## Open Issues` section.
4. **Fix the single most important issue, then stop.** Fix it thoroughly — if it spans multiple files, fix all of them consistently. Once fixed, move the issue to `## Fixed Previously` in `docs/reference/gaps-identified.md`. **Proceed immediately to step 5. Do not fix another issue.**
5. **Run the tests** — Run `{TEST_COMMAND}`. Compare the failing set against the recorded branch-point baseline in `docs/reference/test-baseline.md`. Investigate and fix any **NEW** failure (one not in the baseline) and any new build break. Pre-existing failures from the baseline are NOT your job — log them under `## Won't Fix (Beyond Current Scope)` in `gaps-identified.md` and move on. Do NOT try to make the entire suite green.
6. **Assess the checklist** — Evaluate honestly, then proceed immediately to the Wrap Up phase. Do not go back to step 4.

## Baseline-relative gating

`docs/reference/test-baseline.md` records which tests already failed **before** this work began. "Done" gates on **no NEW failures vs that baseline** (the current failing set must be a subset of the baseline) and **no new build break** — NOT on a fully green suite. The repo may be red on arrival; pre-existing failures are not this work's responsibility and must not block the loop.

A fully green suite does NOT by itself mean done: green over-mocked tests can coexist with an unwired feature. Before checking the wired-and-fed box, run the PROVENANCE GREP — for every new exported field/collaborator/config, `grep -rn <Symbol>` and confirm it is constructed/populated OUTSIDE `*_test.go` and assembled into the real composition root. Apply the PROBE to coverage: "would this test still pass if the prod input were nil?" If yes, it's green-theater. An inert/no-op path logged "acceptable" is an OPEN gap, not done.

## The Checklist (be brutally honest)

Do NOT check a box unless you could defend it in a code review:

{CHECKLIST — each item as `- [ ] {item text}`}

## Wrap Up

Follow these steps in order. **Do not go back to fix more issues.**

**Step A — Commit and push your branch to remote.**

Always commit and push first. Your work is valuable regardless of checklist status.

**Step B — Determine if this focus area passed review.**

All checklist boxes must be honestly checked for the focus area to pass. **Most focus areas need multiple passes — this is normal and expected.** A failing checklist simply means this area needs another pass. Every commit that fixes something is a successful outcome.

**Step C — Update tracking (only if the focus area passed).**

- If the focus area **passed**: Mark that focus area's review as complete in `docs/reference/focus-areas.md`.
- If the focus area **did not pass**: Do NOT update `docs/reference/focus-areas.md`.

**Step D — Output your promise tag and stop.**

Check `docs/reference/focus-areas.md`. Are ALL reviews (single areas and paired areas) now marked complete?

- If **all reviews are complete**: output `<promise>FINIT</promise>`
- If **any reviews remain incomplete**: output `<promise>CLOSER</promise>`

Output exactly one `<promise>` tag, then stop. Do not output anything after the tag.

Generate docs/reference/focus-areas.md

Write docs/reference/focus-areas.md with this structure:

# Focus Areas Review Tracking

This document tracks the systematic review of {MISSION_SHORT — one-line summary}.

Each **single focus area** requires **2 full review passes** before being considered done.
Each **paired focus area** requires **1 full review pass** before being considered done.

A review pass is only checked when the checklist produces a passing result for that area.

---

## Table 1: Single Area Reviews (2 passes each)

| # | Focus Area | Pass 1 | Pass 2 | Status |
|---|---|---|---|---|
{For each SINGLE_AREA, numbered starting at 1:}
| {N} | {Name} (`{key files}` — {review scope description}) | [ ] | [ ] | |

---

## Table 2: Paired Area Reviews (1 pass each)

| # | Pair | Pass | Status |
|---|---|---|---|
{For each PAIRED_AREA, numbered continuing from single areas:}
| {N} | {Area 1} + {Area 2} ({seam description}) | [ ] | |

---

## Review Guidance

### Single Area Reviews — What To Check

**Pass 1 (Correctness & Coverage):**
- All public functions have test coverage (happy path, failure, error, edge cases)
- The code does what the design doc says it should
- Error handling is thorough — no silent failures
- Module boundaries are clean (no leaking types across boundaries)

**Pass 2 (Robustness & Extensibility):**
- Code aligns to the spirit of the design, not just surface conformance
- The component is ready to be extended by future work
- Test assertions test real risks, not just happy-path ceremony
- Edge cases are handled (empty inputs, concurrent access, boundary values)

### Paired Area Reviews — What To Check

Paired reviews verify that two components integrate correctly:
- Data flows cleanly across the boundary
- Error propagation works end-to-end
- No assumptions in one component that the other doesn't satisfy
- The integration tests cover the seams between the pair

Generate docs/reference/gaps-identified.md

Write docs/reference/gaps-identified.md:

# Gaps Identified

Issues found during review. Only the user can move items to the Won't Fix sections.

## Open Issues

_(none)_

## Fixed Previously

_(none yet)_

## Won't Fix (Beyond Current Scope)

---

Phase 5: Review

Show the user a summary:

Ralph review files generated:

  RALPH.md
    Persona:      {first sentence of PERSONA}
    Test command:  {TEST_COMMAND}
    Checklist:     {N} items

  docs/reference/focus-areas.md
    Single areas:  {N} (2 passes each)
    Paired areas:  {N} (1 pass each)
    Total reviews: {TOTAL} passes

  docs/reference/gaps-identified.md
    Empty template ready

  docs/reference/test-baseline.md
    Branch-point baseline: {N} pre-existing failures recorded (gating is NEW-vs-baseline, not full-green)

Want to review or edit any of the generated files before I commit?

If they want to review a file, show its content using the Read tool. If they make manual edits (outside Claude Code), re-read the file to acknowledge changes. If no review needed, proceed to Phase 6.

---

Phase 6: Commit

Stage and commit all generated files plus any historical backups:

git add RALPH.md docs/reference/focus-areas.md docs/reference/gaps-identified.md docs/reference/test-baseline.md
# Also stage historical backups if they were created
git add docs/reference/historical/ 2>/dev/null || true
git commit -m "chore: generate ralph review files via plan-to-ralph"

Tell the user:

Review files committed. To start the ralph review:

  /direct-to-ralph "{MISSION_SHORT}"

Or submit manually:

  ralph-o-matic submit