git:20260306.6aec60a to git:20260306.1c6b68d

---

name: ralph-prompt-generator

description: Use when a user has a rough prompt that needs a staged prompt-improvement workflow for `$ralph-wiggum-codex`, with saved draft/final files and explicit review checkpoints.

---

# Ralph Prompt Generator

Companion skill for `$ralph-wiggum-codex`.

This skill does not exist to synthesize flags first. Its primary job is to improve the prompt itself through a staged prompt-improvement workflow, then finish with a small Ralph-specific handoff.

## Core Rule

Clarify, do not prescribe.

The receiving agent is equally capable. Improve the briefing, preserve the user's boundaries, and avoid doing the downstream agent's job.

## When To Use

Use this skill when:

- The source prompt is ambiguous, bloated, or structurally weak.

- The user wants a reusable prompt for `$ralph-wiggum-codex`.

- The task needs critique and revision, not just runner flag suggestions.

- The user wants saved planning, draft, and final prompt files in the repo.

Do not use this skill when:

- The user already has a production-ready Ralph prompt.

- The user wants `$ralph-wiggum-codex` executed immediately with no prompt rewrite.

- The only missing detail is a minor flag choice that can be handled inline.

## Inputs

Primary input:

- `<user_prompt>`

Optional supporting context:

- `<examples>`

- `<feedback>`

Treat `<examples>` as demonstrations, not new requirements. Treat `<feedback>` as revision guidance, not permission to weaken the original constraints.

## Repo-Backed Workspace

Use this workspace for all saved outputs:

- `docs/prompt-improver-spec/artifacts/implementation_plan.md`

- `docs/prompt-improver-spec/artifacts/task.md`

- `docs/prompt-improver-spec/artifacts/walkthrough.md`

- `docs/prompt-improver-spec/final-prompts/<prompt-name>-draft.md`

- `docs/prompt-improver-spec/final-prompts/<prompt-name>.md`

Determine `<prompt-name>` during planning using a descriptive kebab-case filename. Reuse the saved files on resume instead of redoing earlier analysis from scratch.

Delete the draft file after creating the final prompt.

## Required Workflow

Follow the staged workflow defined in `references/prompt-improver-workflow-codex.md`.

### Phase A

Planning only. Complete Steps 1-2.

Required work:

- Read `<user_prompt>` and any optional `<examples>` / `<feedback>`.

- Extract and normalize examples.

- Quote unclear or problematic phrases from the source prompt.

- Preserve all explicit MUST, MUST NOT, and DO NOT constraints.

- Create `docs/prompt-improver-spec/artifacts/implementation_plan.md`.

- Create `docs/prompt-improver-spec/artifacts/task.md`.

- Choose `<prompt-name>`.

`implementation_plan.md` must include:

- Step 1 example identification

- Step 2 planning analysis

- intent summary

- deployment summary

- task flowchart

- lessons from examples

- chain-of-thought approach assessment

- output format analysis

- variable plan

- structural notes

- ambiguities and questions

- prompt filename

- constraint-preservation checklist

End Phase A at a native Codex review checkpoint after Steps 1-2. Pause and ask the user to review the saved planning artifacts before continuing.

### Phase B

Initial draft only. Complete Step 3.

Required work:

- Read the saved planning artifacts instead of redoing them.

- Write the first improved prompt draft to `docs/prompt-improver-spec/final-prompts/<prompt-name>-draft.md`.

- Update `docs/prompt-improver-spec/artifacts/task.md` to mark Steps 1-3 complete.

- Include clarifying questions only if ambiguities remain.

The draft must:

- define the assistant role clearly

- introduce descriptive XML variables when useful

- preserve all constraints

- clarify the objective

- specify output expectations without pre-solving the task

- add anti-patterns or verification checklists only when they help

End Phase B with the saved draft path and any remaining clarifying questions. Do not emit the Ralph-ready invocation snippet yet.

### Phase C

Critique and revision planning only. Complete Step 4.

Required work:

- Read `docs/prompt-improver-spec/final-prompts/<prompt-name>-draft.md`.

- Append the critique and revision plan to `docs/prompt-improver-spec/artifacts/implementation_plan.md`.

- Update `docs/prompt-improver-spec/artifacts/task.md` for Step 4.

The critique must quote specific problem text and describe:

- issues identified

- areas needing expansion

- structural improvements

- constraint-preservation check

End Phase C at a second native Codex review checkpoint after Step 4. Pause and ask the user to review the critique before continuing.

### Phase D

Revision, final polish, and delivery. Complete Steps 5-6.

Required work:

- Read and reuse all existing prompt-improver artifacts.

- Apply the revision plan to strengthen weak sections.

- Save the final prompt to `docs/prompt-improver-spec/final-prompts/<prompt-name>.md`.

- Delete the draft file at `docs/prompt-improver-spec/final-prompts/<prompt-name>-draft.md`.

- Create `docs/prompt-improver-spec/artifacts/walkthrough.md`.

- Update `docs/prompt-improver-spec/artifacts/task.md` to mark all steps complete.

The final polish must verify:

- all original constraints are preserved

- XML tag usage is consistent when tags are used

- instructions are logically ordered

- the prompt is complete without doing the receiving agent's work

Final delivery must include:

- the completion message ending with `All 6 Steps Complete.`

- the saved final prompt path

- confirmation that the draft file was removed

- a short Ralph-ready invocation snippet that points to the saved final prompt file

## Ralph-Specific Tailoring Is Secondary

After the prompt itself is finished, add only a small Ralph-specific wrapper:

- how to use the saved prompt with `$ralph-wiggum-codex`

- optional validation or progress-scope guidance if it materially helps

- optional flags only when they materially improve the run

The final deliverable is a production-ready prompt file plus a Ralph-ready invocation snippet, not a flags-first handoff block.

## Non-Negotiable Constraints

You must not:

- execute or answer the source prompt's underlying task

- remove or weaken original constraints

- invent missing facts without labeling them

- redo earlier phases from scratch when saved artifacts already exist

- leave the draft file behind after finalizing

- fill the prompt with example outputs that amount to doing the agent's work

- prescribe low-level execution steps unless the user explicitly asked for them

## Prompt Quality Checks

When drafting or revising, explicitly check:

- Clarity: quote confusing phrases and rewrite them

- Structure: fix ordering, grouping, and entry point issues

- Completeness: add missing briefing context, not extra deliverables

- Variables: keep placeholders and XML tags consistent

- Constraints: preserve MUST / MUST NOT / DO NOT rules

- Output format: show structure, not pre-filled answers

- Anti-over-engineering: remove content that does the downstream agent's job

## Optional Ralph Guidance

Model and flag guidance are secondary.

Only consult these references when the final Ralph wrapper actually needs them:

- `references/prompt-improver-principles.md`

- `references/openai-codex-prompting-2026.md`

- `references/ralph-flag-selection-matrix.md`

If a model name or OpenAI capability is uncertain, consult the `openaiDeveloperDocs` MCP dependency declared in `agents/openai.yaml`.