Opt

/opt - PromptForge Optimizer

Optimize a prompt, instruction, system message, or agent brief using the PromptForge pipeline. This core is runtime-neutral; model routing, reasoning effort, tool bindings, and install-specific paths are supplied by the runtime target.

Trigger Behavior

• Use when the user explicitly says opt, /opt, [$opt], opt explain, optimize this prompt, or asks to improve a prompt/instruction.
• Runtime action mode is declared by the target frontmatter metadata:
  • prompt_only: optimize the text and do not execute the optimized request.
  • optimize_execute: optimize the text, show the optimized prompt preview, then execute the optimized request in the same turn.
• If no action mode is declared, default to prompt_only.
• If no prompt text is provided, ask for the text to optimize.

Input Validation

Before optimizing, classify the input:

• Empty input: ask for the prompt text.
• Fewer than 5 words: classify as trivial and explain that no optimization is needed.
• Code-only input: offer to optimize surrounding instructions, comments, or docstrings instead.
• Already optimized PromptForge output: ask whether to re-optimize or explain the prior scoring.
• Non-English input: optimize in the input language.

PromptForge Pipeline

1. Detect the target model family (Model-Family Gate). If the runtime exposes a target model id, branch the rewrite shape accordingly; if unknown, optimize for a non-reasoning target but keep scaffolding light.
2. Classify the input as TRIVIAL, STANDARD, COMPLEX, or PRODUCTION.
3. Decompose the input into labeled blocks — instruction, context, examples, output-format, verification — and flag which blocks are weak or missing (Block Decomposition). Rewrite to fix the flagged blocks; preserve blocks that already work rather than rewriting wholesale. (For run-trace failure attribution on agentic prompts, see Technique Selection.)
4. Search the available knowledge base for a high-quality existing pattern when the runtime provides one.
5. Select prompt-engineering techniques that match the weakness in the flagged blocks.
6. Rewrite the prompt as an improved agent brief, not as a paraphrase of the user request. Preserve user intent while adding operational structure, evidence ordering, source boundaries, validation checks, exception policy, and output/update contract. Do not inflate length: 120% of the input token count is the soft authoring target (the hard fail line is 1.5x — see Scoring Rubric Token-efficiency), unless you are adding a structured output schema or contract the input genuinely lacked.
7. Score the result against the Scoring Rubric.
8. Refine if the total is below the class target or any single axis is below its floor.

Model-Family Gate

• Reasoning-native target (extended-thinking modes, o-series and equivalents): suppress chain-of-thought, scratchpad, and "think step by step" scaffolding — it overrides the model's internal reasoning and measurably degrades output. Emit task framing, a clear output contract, and a verification layer only. State in Notes: "CoT scaffolding suppressed — reasoning-model target."
• Non-reasoning target (or unknown): step-back framing, explicit reasoning structure, and worked examples remain valid.
• Few-shot examples for reasoning-native targets serve output-format alignment, not reasoning lift. Never copy CoT scaffolding written for one family into the other.

Technique Selection

• Match the target model family first (see Model-Family Gate) — reasoning-native and non-reasoning targets need different prompt shapes.
• Reasoning or analysis: for non-reasoning targets, use step-back framing and explicit evaluation criteria. For reasoning-native targets, drop that scaffolding and rely on the output contract plus a verification layer.
• Code or technical work: add implementation constraints, verification commands, and regression expectations.
• Multi-step agentic work: add planning, tool-use boundaries, checkpoints, and failure handling. When a prior run trace is supplied, attribute the failure to the specific tool call, retrieval miss, or context-truncation event and rewrite only the implicated instruction rather than the whole prompt.
• Ambiguous prompts: rephrase intent, state assumptions, and request missing inputs only when needed.
• Production prompts: include uncertainty calibration (the hedging gate from the Scoring Rubric), output self-consistency checks, and persistence instructions where the runtime supports them.

Detail Floor

• For COMPLEX and PRODUCTION prompts, the optimized prompt or preview must be detailed enough to execute: objective, context, evidence hierarchy, scope boundaries, reconciliation checks, failure handling, and output contract where relevant.
• Never replace a COMPLEX or PRODUCTION optimization with a title, vague summary, task inventory, or one-line instruction. A preview may be shorter than the full prompt only if it preserves the operational detail an agent needs to act correctly.
• For STANDARD prompts, keep the result concise but still include concrete constraints and expected output.

Grounding Gate

The current user request is the scope authority. Conversation memory, broader context, knowledge-base hits, and reference examples may help interpret named artifacts, but they must not add new objectives, write targets, systems, datasets, exclusions, or business framing.

Before scoring a COMPLEX or PRODUCTION preview, check:

• Write targets are in scope only when the current request names them. Do not instruct updates to persistent destinations, external tools, or external records unless the user explicitly asked for that destination in the current prompt.
• If the user says "ingest" without naming a destination, default to a local extraction/evidence record and ask where to sync it; do not infer a persistent destination from memory.
• Negative guardrails can also contaminate scope. Do not name unrelated domains in exclusions unless the user introduced those domains. Use generic boundaries such as "keep separate from unrelated workflows."
• If memory suggests a likely destination or project link, surface it as an optional confirmation question, not as an instruction.
• Cap the score at 79 if the preview includes an unrequested persistent update target or a negative guardrail naming an unrelated domain.
• Injection surface (any prompt that ingests untrusted, external, or user-supplied data): separate instruction zones from data zones with explicit structural delimiters such as XML-style tags or clearly fenced sections, and ensure no user-supplied variable sits where it could be read as a system instruction. Cap the score at 79 if instruction and data boundaries are collapsed in a prompt that consumes external or user-controlled content.

Preview Quality Gate

For COMPLEX and PRODUCTION prompts, apply this gate before returning Status: PASS:

• The preview must be a synthesized execution brief, not a sentence that begins with or structurally echoes "for every...", "search...", "update...", or the user's raw task list.
• The preview must include at least five of these six elements: primary objective, evidence/source hierarchy, exact scope boundaries, reconciliation or verification checks, exception/failure handling, and output/update contract.
• The preview must name only key domain artifacts that are present in the current user request or attached/currently visible task materials, and state how conflicts are resolved.
• The preview must preserve unresolved or unverifiable items as exceptions instead of implying inference or silent completion.
• Treat reference examples as format examples only. Never copy their domain nouns, systems, tools, artifacts, files, or business framing into an unrelated prompt.
• Cap the score at 84 if the preview introduces unmentioned systems, workstreams, storage destinations, people, or workflow artifacts from memory or examples.
• If the user asks to be asked questions or to confirm inputs interactively, surface those questions directly in the optimized prompt or execution plan. Do not bury them as a report section or deferred artifact.
• If the preview is a paragraph, make it 120-220 words for COMPLEX/PRODUCTION prompts. If it would be clearer, use a compact structured block with 4-7 labeled bullets.
• Cap the score at 89 unless the preview passes this gate. Cap the score at 84 if the optimized prompt merely expands the user's wording without adding a stronger operating model.

Scoring Rubric

Score the rewrite on five core axes (0-20 each): clarity, completeness, specificity, robustness, execution-fit. Their sum is the score on a /100 scale.

Class targets (minimum total to return PASS): TRIVIAL — n/a (no optimization needed); STANDARD — 75; COMPLEX — 85; PRODUCTION — 90. Per-axis floor: no single axis below 12/20.

Two pass/fail gates run alongside the axes:

• Calibration: when the input is ambiguous, multi-interpretation, or low-evidence, the rewrite must preserve or add explicit uncertainty language — hedges, confidence qualifiers, or "confirm before acting" clauses. FAIL if the rewrite strips all hedging from an input that carried uncertainty; a confident, fluent, wrong prompt is worse than a cautious one.
• Token-efficiency: FAIL if the rewrite exceeds the hard ceiling of 1.5x the input token count without adding a genuinely new structured schema, contract, or evidence model. (The Pipeline's 120% is the soft authoring target; 1.5x is the hard fail line.) For COMPLEX and PRODUCTION previews, the Preview Quality Gate's required 120-220-word floor and its five-of-six operating-model elements ARE such an evidence model by definition: do not FAIL a preview on token count solely for expanding a short input up to that required floor. This carve-out is bounded — it licenses expansion only up to the floor and its required elements; any content beyond what the Preview Quality Gate and Detail Floor actually require remains subject to the 1.5x ceiling and FAILs if it pads without adding a required element.

Cap reconciliation: the Grounding Gate (cap 79) and Preview Quality Gate (caps 79/84/89) impose upper bounds on the same /100 scale. Compute the axis total first, then clamp the final score to the minimum of (axis total, every triggered cap).

Per-axis ablation check: a high total can mask one weak axis. After scoring, inspect each axis in isolation; a single axis below the 12/20 floor downgrades the result even when the total meets the class target (see Status mapping).

Status mapping (single source of truth)

• ERROR — input cannot be optimized, or a CRITICAL gate fails: scope contamination (Grounding Gate), collapsed injection boundary, or Calibration FAIL on an uncertain input. CRITICAL gates block PASS; refine and re-score before emitting any other status.
• CONDITIONAL — total meets the class target but a single axis is below the 12/20 floor (masked weakness). Name the weak axis.
• WARN — total is below the class target, or Token-efficiency FAILs. Flag the gap.
• PASS — total ≥ class target, no axis below floor, Calibration PASS, no triggered CRITICAL gate.

Severity labels map directly to status: CRITICAL → ERROR (block); single-axis-below-floor → CONDITIONAL; below-target or Token-efficiency FAIL (MAJOR) → WARN; style/ordering (MINOR) → note only.

Context Ordering (PRODUCTION)

For PRODUCTION-tier prompts that run many times against a shared static prefix, order blocks by mutability to maximize prompt/KV-cache reuse: invariant content first (role, standing instructions, output schema), variable content last (user query, retrieved documents, per-call examples). Note the cache boundary in the output ("content above this line is cache-eligible"). Do not reorder when it would break a required reading order or target a runtime without prefix caching.

Delivery Format

Return:

PromptForge | Class: <CLASS> | Target model: <model id or "unspecified"> | Techniques: <list>
Status: PASS|WARN|CONDITIONAL|ERROR | score=<N>/100 | iterations=<N>
Gates: <COMPLEX/PRODUCTION only — only gates that fired or capped, e.g. "Grounding cap 79 (unrequested write target)", "Preview-Quality cap 89", "Calibration PASS"; omit this line entirely when none fired>

Optimized Prompt:
<prompt>

Notes:
<brief explanation of material changes>

When the target model is known, stamp it on the status line. A prompt optimized for one model version may regress on another; if the user later changes target model, advise re-optimization rather than assuming the prompt still holds.

Emit the Gates: line only for COMPLEX and PRODUCTION classes, list only the gates that actually triggered or capped, and derive it strictly from the Status mapping computation — it is a readout of that single source of truth, never an independent judgment. Omit the line entirely when no gate fired.

For opt explain or prompt_only mode, include the scoring rationale and applied techniques when useful. Make the optimized prompt the primary output.

For optimize_execute mode:

1. Run the PromptForge pipeline.
2. Show Optimized prompt preview: before execution.
3. For COMPLEX and PRODUCTION work, make that preview a dense executable paragraph or structured block that passes the Preview Quality Gate. Prefer structure when the task involves multiple evidence sources, records, tables, code changes, or reconciliation.
4. Execute the optimized request immediately.
5. Make the final answer the result of the executed task, while preserving the optimized prompt preview in the response.

Preview Reference Examples

Weak preview, do not emit:

Read the screenshot table, compare prices with the website, check formulas, ask cost questions, and write a report.

Acceptable COMPLEX preview:

Treat the screenshot table as the extraction source for row labels, quantities, unit costs, formulas, and visible notes; treat the public website as the authority only for the current customer-facing sell price. Keep the task limited to extraction, website comparison, formula validation, direct owner questions, and a local evidence report unless the user names a persistent destination. For each row, compare screenshot values against website sell prices, recompute any visible formulas, flag unreadable/cropped cells and site mismatches, and preserve assumptions requiring owner confirmation. If the user asked to be asked about costs, ask those questions directly before or alongside the report rather than hiding them in a backlog. Deliver sections for extracted table, website cross-checks, formula validation, owner questions, and exceptions; if a sync destination is needed, ask the owner to confirm it.

Runtime Boundary

The generated runtime target decides the model, reasoning effort, and any local enrichment files. The core must stay portable and must not copy one runtime's frontmatter into another runtime.