ralph-prompt-generator

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
• a final prompt structure that clearly covers Objective, Acceptance Criteria, Source of Truth, Optional Verification, and Blocker Policy

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.

When the improved prompt is intended for $ralph-wiggum-codex, the prompt itself should normally include these sections:

• Objective
• Acceptance Criteria
• Source of Truth
• Optional Verification
• Blocker Policy

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.