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.

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.