Prompt Optimizer

Rewrite a prompt, a task description or a whole workflow file so two runs on the same input take the same actions in the same order: drop personas and courtesy, turn nested conditionals into gates, move validation ahead of side effects, and give every value a deterministic source. Optionally runs the result afterwards. Use when the user says "optimise this prompt", "optimise the prompt below", "optimise this task and run it", "prompt optimizer", "make this deterministic", when a workflow behaves differently between runs, or when an older prompt has to become a skill.

How to use

Use this on any agent workflow that behaves inconsistently between runs.

Prompt

Prompt Optimizer

Rewrite a workflow so that two runs on the same input take the same actions in the same order.

CRITICAL CONSTRAINTS (FAIL-CLOSED)

  1. Never Mandate A Placeholder: a value the agent cannot verify does NOT get a fallback string. It gets a deterministic source — a command whose output is pasted — or the field is omitted. UNKNOWN, TBD and "use today's date" are defects, not safety: an agent told to write UNKNOWN when unsure writes it every time, and the field dies. A missing value is recoverable; a wrong one is not.
  2. Never Strip A Functional Marker: emoji, heading shapes and line prefixes may be a parsing contract, not decoration. Check what reads the file before removing anything that looks ornamental. ## 🚨 is a mandatory block boundary in @.agents/skills/cebreus-memories/GOTCHA-FORMAT.md.
  3. Never Drop An Instruction: rewriting is compression, not pruning. A rule that looks redundant stays, and gets reported as a question. Only the user removes a rule.

1. Pick The Target

Gate: the request names a file path. The target is that file, and the rewrite is written back to it.

Otherwise. The target is the text of the request itself — a pasted block, or the instruction just given — and the rewrite goes back into the conversation. Nothing is written to disk.

The path decides. Do not ask which.

For a file target, read the whole file plus every file it references: a workflow that reaches for a helper script or a format document cannot be judged from its own text.

For a skill file (.agents/skills/<name>/SKILL.md) the frontmatter is part of the contract: name in lowercase-hyphen form matching its directory, and description stating both the capability and the quoted phrases that should trigger it. agent:check enforces the name; nothing enforces the triggers, so read them and check no other skill claims the same phrase.

2. Diagnose

Sort every finding into exactly one category.

  • Non-determinism: vague verbs ("prefer", "try", "consider", "if appropriate"); nested IF/ELSE; a value the agent is expected to recall rather than read; validation that runs after the step it guards.
  • Fluff: personas (**Role:** Senior …), courtesy, decorative headings, transitions, and rationale that changes no action. Rationale that explains why a rule exists stays — it is what stops the next reader from "fixing" the rule.
  • Missing boundary: unrestricted tool use, assumed context that was never established, a step with no defined failure, or a side effect with no guard.

3. Rewrite Rules

  1. No persona. State the job, not who performs it. A skill opens with its objective in one line.
  2. Fail-closed section. Every "NEVER do X" and every hard boundary goes into one ## CRITICAL CONSTRAINTS (FAIL-CLOSED) block. A constraint outside it is not a constraint.
  3. Fail-first ordering. Every check a step depends on runs BEFORE that step's first side effect. A run that creates a directory and only then discovers its input was invalid has left a mess behind; move the check above the write.
  4. Gates, not branches. Replace each conditional with a linear gate naming its STOP condition.
    • Bad: If staging is empty, ask the user. Else, run git commit.
    • Good: Gate: if staging is empty, STOP. then Run: git commit.
  5. Deterministic sources. Where the original expects the agent to know something, name the command that produces it and instruct that its output be pasted verbatim.
  6. Brevity. Imperative commands. Dense bullets instead of nested lists and one-row tables.
  7. Keep what parses. Preserve exact error strings, file paths, markers and command names.

4. When Not To Rewrite

Report and stop instead of rewriting when the workflow is already dense and deterministic, or when other files reference its sections by number or title. Renumbering a section that @-references point at breaks them silently. Say so and propose the smaller edit.

5. Output

  1. Flaws Identified: one bullet per finding, each tagged Non-determinism, Fluff or Missing boundary, and each naming what replaces it.
  2. Gate Map: every original branch mapped to its replacement gate, with the STOP condition and the action that follows.
  3. Improved Version: for a file target, write it to that file and say so. For a text target, output it after a --- separator with no fence around it. Do NOT wrap it in a fenced code block: prompts and workflows contain fenced blocks, and the nesting breaks the outer fence.
  4. Questions: every rule that looked redundant but was kept, per constraint 3. Empty is a valid answer.

6. Run It

Only when the request asked for execution ("and run it", "optimise and execute").

  1. Show first. Output sections 1 to 4 before running anything. The point of the rewrite is that the user sees what changed; executing a silently rewritten instruction defeats it.
  2. Gate on side effects. If the optimised instruction writes, deletes, commits, publishes or spends money, STOP after showing it and ask for confirmation. Read-only work proceeds.
  3. Run the optimised version, not the original. Say which one ran.