Prompt Optimizer

Prompt Optimizer

Turn a rough prompt into one that reliably produces outstanding results. The core insight: most prompts fail not because the model is weak, but because the prompt is missing information the model needs – who it's for, what "good" looks like, what format to use, what to avoid. Your job is to supply that missing information, either from the user's context or by asking.

The Golden Rule

Never optimize a prompt you don't understand. A beautifully structured prompt built on guessed context produces confident garbage. The clarification gate (Step 2) exists because asking one good question beats inventing three plausible-but-wrong constraints.

Equally: never bloat. A 10x prompt is not 10x longer. Every line you add must earn its place by changing the output. Generic filler ("be professional and thorough") is noise the model ignores – or worse, obeys at the cost of the user's actual intent.

Workflow

Step 1 – Diagnose the prompt

Read the user's prompt and silently score it against the Seven Pillars (details + examples: references/techniques.md):

1. Role – is the model given a specific identity that shapes voice and judgment (where the task benefits from one)?
2. Context – does the model know the situation, audience, and what the output is FOR?
3. Task precision – is the ask specific and decomposed, or a vague verb ("write about X")?
4. Format – is the output structure specified (length, sections, medium, style)?
5. Examples – would 1–3 examples of "good" lock in the pattern? (Highest-leverage lever per every major lab's docs.)
6. Reasoning room – does the task benefit from asking the model to think/plan before answering?
7. Success criteria & guardrails – does the prompt define what "great" means and what to avoid?

Also detect the target: which AI and use-case is this prompt for? (Claude/ChatGPT/Gemini chat, an agentic coding tool, an image/video generator, a system prompt for an app). Optimization differs by target – see references/techniques.md §Target-specific tuning.

Step 2 – The clarification gate

Split what's missing into two buckets:

• Critical gaps – things you cannot sensibly default and that would change the whole prompt: the actual goal/deliverable, the audience, the target AI (if it changes tactics), domain facts only the user knows, hard constraints (length, tone, brand rules, tech stack).
• Defaultable gaps – things a sensible assumption covers. Don't ask about these; assume and declare the assumption in the final output so the user can correct it.

If there are critical gaps: ask before optimizing. Batch everything into ONE round of at most 3–4 sharp questions (use the AskUserQuestion tool if available, with concrete options – options are faster to answer than open questions). Never interrogate across multiple rounds; if answers still leave holes, default + declare.

If nothing critical is missing, skip straight to Step 3 – don't ask questions for the sake of it. A user who provided rich context should get an instant result.

Step 3 – Rebuild the prompt

Construct the optimized prompt using this anatomy (order matters – details in references/techniques.md):

1. Role – one or two sentences, specific and domain-relevant: not "you are a writer" but "you are a direct-response copywriter known for [specific trait relevant to the task]". The specificity does the work – research shows superlative hype ("top 0.1%", "world's best") adds nothing for factual/analytical tasks and can even hurt accuracy; it's acceptable flavor only for creative/voice work. For factual tasks, keep the role minimal and spend the tokens on context and success criteria instead.
2. Context block – the situation, audience, and purpose. What the model needs to know, nothing it doesn't.
3. Task – the precise ask, decomposed into steps if multi-part. One prompt, one job; split unrelated jobs into separate prompts.
4. Format spec – exact output structure: length, sections, medium, what to include/exclude.
5. Examples (when they'd help) – 1–3 short examples of the desired output pattern, or an excerpt of the user's own voice to match.
6. Reasoning directive (for complex tasks) – instruct the model to plan/outline/think through the approach before producing the final output.
7. Success criteria + guardrails – 2–4 bullets defining "great", plus negative constraints phrased positively where possible ("write at a 9th-grade reading level" beats "don't be too complex").
8. Escape hatch – for prompts the user will run later: "If any information you need is missing, ask me before answering." This makes the optimized prompt self-clarifying too.

Use the structure conventions of the target model: XML-style tags (<context>, <examples>) for Claude, markdown headers for ChatGPT/general use. For long prompts, put reference material at the top and the instruction at the bottom.

Templates for common prompt types (writing, coding, analysis, image gen, system prompts): references/templates.md.

Step 4 – Deliver

ALWAYS use this exact output structure:

## Your optimized prompt

```
[the full optimized prompt, in a fenced block, ready to copy-paste]
```

## What changed and why

| Change | Why it matters |
|---|---|
| [added X] | [the specific failure it prevents / improvement it causes] |

*(3–6 rows – the highest-impact changes only)*

## Assumptions I made
- [each defaultable gap you filled + how to change it]

*(omit this section if you made none)*

Then offer – don't just do – the next step: "Want me to run it?" (if runnable here) or "Want a variant tuned for [other target]?" If the user asked you to optimize AND execute in one breath, run the optimized prompt immediately after showing it.

Step 5 – Iterate on results (when asked)

If the user comes back with "the output was too X / missed Y": don't rewrite from scratch. Diagnose which pillar failed (usually format spec or success criteria), patch that section surgically, and show only the diff. Prompt optimization converges in 1–2 iterations when each fix targets the observed failure.

Calibration

Match effort to the prompt's stakes:

• Quick prompt (one-off question, casual use) → light touch: sharpen the task, add format + audience, skip the ceremony. Deliver in seconds, no questions unless the goal itself is unclear.
• Workhorse prompt (will be reused: content pipeline, client work, coding tasks) → full Seven Pillars treatment + escape hatch + declared assumptions.
• System prompt / agent instructions (runs unattended, high blast radius) → full treatment plus edge-case handling, refusal behavior, and a test suggestion: "run it on these 3 inputs before trusting it".

Anti-patterns (the failure modes of prompt optimizers)

• Over-stuffing – adding every technique to every prompt. A haiku request does not need chain-of-thought and success criteria.
• Intent drift – the optimized prompt is impressive but no longer asks for what the user wanted. Re-read the original before delivering; the user's words about the goal always win over your embellishments.
• Invented constraints – never add domain facts, numbers, or claims the user didn't give you. Constraints you fabricate become confident errors downstream.
• Cargo-cult tokens – tip offers, threats, ALL-CAPS pleading, "take a deep breath" incantations. Evidence says these are noise on modern models; structure and context are what move quality. See references/techniques.md §Myths.
• Question paralysis – asking 8 questions before showing anything. One round, max 4, only critical gaps.