Help us improve
Share bugs, ideas, or general feedback.
From pr-review
Automatically generate ralph review files (RALPH.md, focus-areas.md, gaps-identified.md) from spec and design docs without interactive Q&A
npx claudepluginhub dbinky/dbinky-skill-set --plugin spec-to-designHow this skill is triggered — by the user, by Claude, or both
Slash command
/pr-review:auto-ralph-prepThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are generating ralph-o-matic review files without user interaction. This skill derives all configuration from the feature spec, design docs, implementation plans, and codebase scan — replacing the interactive Q&A in `plan-to-ralph`.
Creates p5.js generative art with seeded randomness, noise fields, and interactive parameter exploration. Use for algorithmic art, flow fields, or particle systems.
Share bugs, ideas, or general feedback.
You are generating ralph-o-matic review files without user interaction. This skill derives all configuration from the feature spec, design docs, implementation plans, and codebase scan — replacing the interactive Q&A in plan-to-ralph.
This is invoked either directly (/auto-ralph-prep) or via plan-to-ralph --auto.
Parse the following from the user's command or calling skill:
SPEC_PATH (required): Path to the feature spec (e.g., docs/specs/user-auth-spec.md)DESIGN_GLOB (optional): Glob for design docs (default: auto-derived from spec path by replacing -spec.md with -design-phase-*.md in the superpowers specs directory)PLAN_GLOB (optional): Glob for implementation plans (default: auto-derived similarly)--slug SLUG (optional): Feature slug for commit messages (default: derived from spec filename)Verify git repository:
git rev-parse --is-inside-work-tree
Verify spec file exists. If missing, stop with an error.
Check if any of these files exist:
RALPH.mddocs/reference/focus-areas.mddocs/reference/gaps-identified.mdIf none exist: Skip to Phase 2.
If any exist: Archive them before regenerating, using the same pattern as plan-to-ralph:
docs/reference/historical/ if it doesn't exist.YYYY-MM-DD.docs/reference/historical/ as YYYY-MM-DD-historical-{filename}.md — do NOT copy it. The original must no longer exist at its working-tree location afterward.-2, -3, etc.Why move instead of copy: Phase 5 regenerates each file fresh from the template embedded in this skill, which carries the required control semantics — notably the iteration/wrap-up protocol and the <promise> tag logic that lets the ralph server stop after repeated "no progress" iterations. Moving the originals out (rather than copying) guarantees they are absent when Phase 5 runs, so a previously mangled RALPH.md whose loop semantics were stripped can never survive into the new run. This subsumes the old legacy-format migration: any legacy or mangled RALPH.md is archived and replaced wholesale.
Read these files in full:
SPEC_PATHDESIGN_GLOBPLAN_GLOBCLAUDE.md (if it exists) for project constraintsUse the Agent tool with subagent_type: "Explore" to discover codebase structure. Same scan prompt as plan-to-ralph Phase 2, with the spec's purpose as CONTEXT.
Derive all 7 values that plan-to-ralph normally asks interactively:
Extract from the spec's purpose/goal/overview section. Format as:
Review and refine the implementation of {feature description} per the spec at
{SPEC_PATH}. Verify correctness against the spec, ensure test coverage, fix gaps, and polish the implementation to production quality.
Auto-detect from project files:
Makefile with test target -> make testpackage.json with test script -> npm testgo.mod -> go test ./...pyproject.toml -> pytest tests/ -vCargo.toml -> cargo testIf nothing detected, default to make test.
Generate based on the spec's domain, the project's tech stack, and the codebase patterns:
You are a senior {LANGUAGE} engineer specializing in {DOMAIN_FROM_SPEC}. You understand {ARCHITECTURE_PATTERNS} and care deeply about {QUALITY_ATTRIBUTES_FROM_SPEC}. You review code with the rigor of a principal engineer preparing for a production deployment.
Derive from THREE sources, generating a comprehensive list:
From implementation plan tasks: Each plan task file becomes a focus area (Component category).
From domain analysis of the spec: Identify domain concepts that span multiple files — business entities, workflows, cross-cutting concerns. Each becomes a focus area (Domain Concept category).
From vertical slice analysis: Trace end-to-end paths through the system described in the spec — API endpoint -> business logic -> data layer -> response. Each becomes a focus area (Vertical Slice category).
Aim for as many single focus areas as needed for deep coverage of new, impacted, and adjacent code. Each gets 2 review passes, so 20 areas = 40 passes. Consolidate related files into a single area rather than listing each file separately — a focus area should be a logical unit of review, not a single file. Fewer, broader areas are better than many narrow ones.
Derive from cross-references between focus areas:
Each paired area gets 1 review pass. Aim for sufficient coverage to assure boundary and call pattern correctness — focus on the highest-risk integration seams rather than exhaustively pairing everything.
Always include these 3 universal items:
{TEST_COMMAND})docs/reference/gaps-identified.md for this focus areaAdd items derived from:
{SPEC_PATH}"Pull from:
CLAUDE.md constraints that apply to automated code workCreate docs/reference/ directory if it doesn't exist.
Read the example files for exact formatting reference before generating:
${CLAUDE_PLUGIN_ROOT}/skills/plan-to-ralph/docs/reference/example-focus-areas.md${CLAUDE_PLUGIN_ROOT}/skills/plan-to-ralph/docs/reference/example-gaps-identified.mdGenerate all 3 files. The RALPH.md template is reproduced in full below — write it verbatim, substituting only the {VARIABLES} from Phase 4. For focus-areas.md and gaps-identified.md, use the same templates as plan-to-ralph Phase 4 (reference that skill for their exact structure).
CRITICAL — do not summarize or abridge
RALPH.md. TheMISSION,PERSONA,TEST_COMMAND,CHECKLIST, andEXTRA_CONSTRAINTSvalues you derived in Phase 4 are only the variable substitutions. They are NOT the whole file.RALPH.mdalso contains fixed control machinery — the## Tracking System,## Steps,## Wrap Up, and<promise>tag sections — that drives the iteration loop and lets the ralph server stop after repeated "no progress" passes. If you generateRALPH.mdfrom just the five variable sections, you will strip the loop semantics and the run will never terminate correctly. Reproduce every section shown below.
Write RALPH.md in the repository root with this exact structure (substitute only the {VARIABLES}; keep every other section verbatim):
# 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. Small, focused passes are more reliable than ambitious ones.
- **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
Review one area, fix ONE issue, test, commit, stop. Resist the urge to keep fixing.
1. **Read the Tracking File** — Read `docs/reference/focus-areas.md` and pick a review focus area that hasn't been completed yet. Progression order: complete all **Pass 1** single area reviews, then **paired area** reviews, then **Pass 2** single 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 2-5 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.
docs/reference/focus-areas.md — using SINGLE_AREAS and PAIRED_AREAS, in the exact structure from plan-to-ralph Phase 4 (match example-focus-areas.md).docs/reference/gaps-identified.md — empty template, exact structure from plan-to-ralph Phase 4 (match example-gaps-identified.md).After writing RALPH.md, verify it contains the ## Steps, ## Wrap Up, and both <promise>FINIT</promise> / <promise>CLOSER</promise> tags before continuing. If any are missing, regenerate the file — it is incomplete.
git add RALPH.md docs/reference/focus-areas.md docs/reference/gaps-identified.md
git add docs/reference/historical/ 2>/dev/null || true
git commit -m "chore: generate ralph review files for {SLUG}"
Output a brief summary (no user review needed):
Ralph review files generated for {SLUG}:
RALPH.md — {PERSONA_FIRST_SENTENCE}
focus-areas.md — {N} single areas, {M} paired areas ({TOTAL} review passes)
gaps-identified.md — empty template
Files committed. Ready for /auto-ralph-submit or ralph-o-matic submit.
On failure at any phase, send Teams notification via ralph-o-matic notify with error details and stop.