Help us improve
Share bugs, ideas, or general feedback.
From ralph-o-matic
Generates ralph-o-matic review configuration files (RALPH.md, focus-areas.md, gaps-identified.md) through interactive Q&A, with backup and archival support.
npx claudepluginhub dbinky/ralph-o-matic --plugin ralph-o-maticHow this skill is triggered — by the user, by Claude, or both
Slash command
/ralph-o-matic:plan-to-ralphThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are generating ralph-o-matic review files through interactive Q&A. This skill produces three files that configure a ralph refinement run:
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides systematic root-cause debugging when tests fail, builds break, or unexpected errors occur. Provides a structured triage checklist to preserve evidence, localize, and fix issues instead of guessing.
Share bugs, ideas, or general feedback.
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.
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.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."
Skip this phase if --reset was passed.
Check if any of these files exist:
RALPH.mddocs/reference/focus-areas.mddocs/reference/gaps-identified.mdIf none exist: Skip silently to Phase 2.
If any exist: Archive them before regenerating.
docs/reference/historical/ if it doesn't exist.YYYY-MM-DD.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.mdfocus-areas.md → YYYY-MM-DD-historical-focus-areas.mdgaps-identified.md → YYYY-MM-DD-historical-gaps-identified.md-2, -3, etc. For example, if 2026-03-12-historical-RALPH.md already exists, use 2026-03-12-historical-RALPH-2.md.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.
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:
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.
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.Entry points — Files like main.go, main.py, index.ts, Program.cs, app.py, server.ts, Dockerfile
Config/infra — CI/CD workflows (.github/workflows/), docker files, migration directories, config directories
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
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.
Ask questions one at a time. Skip questions that CONTEXT already answers.
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.
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.
Generate a persona paragraph based on:
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:
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.
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:
Store the final list as SINGLE_AREAS.
Generate suggested pairings from the selected single areas:
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.
Present the proposed checklist:
Proposed review checklist (assessed each pass):
Universal (always included):
[1] All tests pass (`{TEST_COMMAND}`)
[2] No open issues in `docs/reference/gaps-identified.md` for this focus area
[3] The focus area is complete and polished — you'd be proud to ship it
Proposed (based on your project):
[4] {proposed item based on context, e.g., "The code aligns with the design doc"}
[5] {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:
Store the final checklist as CHECKLIST.
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.
Write all 3 files. Create docs/reference/ directory if it doesn't exist.
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}`. Investigate and fix each failure.
6. **Assess the checklist** — Evaluate honestly, then proceed immediately to the Wrap Up phase. Do not go back to step 4.
## 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.
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
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)
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
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.
Stage and commit all generated files plus any historical backups:
git add RALPH.md docs/reference/focus-areas.md docs/reference/gaps-identified.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