prompt-optimize

Prompt Optimization

CRITICAL RULES

1. Read the prompt first. If $ARGUMENTS is a file path, read the file. If inline text, use it directly.
2. Never modify the user's original prompt until they approve a variant.
3. Show the frontier. Efficiency vs effectiveness is the user's call, not the optimizer's: present variants along that axis with honest cost labels, and let the user pick. --optimize-for is the shortcut for users who already know their pole.
4. Never enter plan mode. Execute immediately.

Step 1: Analysis and variant frontier (single subagent pass)

Execute the full analysis and variant generation in a single prompt-engineer subagent call. The agent analyzes first, natively, and returns only the observable artifacts defined in Phase 2: no explicit reasoning scaffold is imposed on it, per its own anti-pattern rules for reasoning models.

Agent:
  subagent_type: "prompt-engineer"
  description: "Analyze the prompt and generate the variant frontier"
  prompt: |
    You are evaluating and optimizing a prompt.

    ## Input
    - Original Prompt: [Insert the prompt from $ARGUMENTS]
    - Optimization Target: [--optimize-for flag value, or "frontier" when absent]
    - Target Model: [--model flag value, default "claude"]

    ## Phase 1: Analysis (private)
    Analyze the prompt thoroughly before writing any output. Extract its behavioral contract
    first, then classify the archetype and score on a 1-5 scale only the rubric dimensions that
    archetype wants, marking the rest N/A. Identify ambiguities, missing edge cases, structural
    weaknesses, and injection vulnerabilities.
    Do not include this working in the response: Phase 2 defines the only output you produce.

    Usage-profile check: determine how the prompt is used (one-off, repeated system prompt,
    agent loop) and whether prompt caching applies. Which tokens matter follows from this:
    output tokens bill at full price and dominate latency; a cached prefix bills ~0.1x on
    reads, so shortening it saves ~10% of what it appears to, and cache-breaking edits
    re-bill it at 1.25x.

    Reasoning-pattern check: first determine the target model class. For reasoning models
    (extended thinking, o-series, R1 class), default to NO explicit scaffold: direct
    instructions plus precise success criteria; consult the "Reasoning models change the
    defaults" section of `${CLAUDE_PLUGIN_ROOT}/references/reasoning-patterns.md` before adding
    any pattern. Otherwise, decide whether the task would benefit from a structured
    reasoning scaffold beyond plain instructions (CoT, Step-Back, ReAct, Tree-of-Thought,
    Self-Consistency, Reflexion, Plan-and-Solve, Least-to-Most, Self-Ask, Skeleton-of-Thought).
    If yes, read `${CLAUDE_PLUGIN_ROOT}/references/reasoning-patterns.md`, pick the pattern
    that matches the task shape using the selection cheat sheet, and apply it in Phase 2.
    For the efficiency variant, always consult that file's token-efficient patterns
    (Chain of Draft, Concise CoT, token-budget prompting, Sketch-of-Thought) and its
    "Cost-aware selection" section: the efficiency pole is built from those techniques,
    not from bare word-deletion.
    If the existing prompt already scores 4+ on every dimension, do not add a pattern just
    for completeness -- record the decision in the analysis instead.

    ## Phase 2: Output
    Based on your analysis, respond strictly in this format:

    ### Diagnostic Scorecard (original, predicted)
    State the archetype in one line, then one row per applicable dimension. Include the
    conditional dimensions (output determinism, tool-use correctness, trust boundaries,
    evalability, creative latitude) only when this archetype wants them, and list the ones you
    marked N/A with a short reason underneath.

    | Dimension | Score (1-5) | Key issue |
    |-----------|:---:|-------|
    | Intent alignment | X | ... |
    | Instruction clarity | X | ... |
    | Constraint correctness | X | ... |
    | Model fit | X | ... |
    | Context efficiency | X | ... |
    | Robustness | X | ... |

    ### Variant Frontier
    Produce 3 variants by default:
    - **A. Max effectiveness**: prioritize quality, robustness, and output control; token cost is secondary.
    - **B. Balanced**: resolve the analysis issues at neutral or lower token cost.
    - **C. Max efficiency**: minimum tokens at estimated parity, built with a token-efficient
      technique where reasoning is involved.

    Collapse to fewer variants only when they would genuinely converge (trivial or already
    near-optimal prompts); say that you did and why. Each variant is a fully rewritten,
    ready-to-use prompt in its own fenced block. Use XML tags if the target model is Claude
    and the prompt mixes instructions, context, or examples; headings suffice for simple prompts.

    ### Comparison
    | Variant | Tokens (est.) | Delta vs original | Technique applied | Predicted effect (unmeasured) | What you give up |

    Token estimates: characters/4 on the prompt text, labeled "est.". If a variant also
    constrains reasoning or output length, state the expected output-token effect
    separately: that is where most of the real savings live.

    ### Behavioral changes
    For each variant, report what changed in behavior rather than in wording: constraints
    strengthened or relaxed, behaviors removed or added, interface changes, tool-policy or
    reasoning-strategy changes, trust boundaries hardened or weakened. Print only the lines that
    are true. If a variant changes nothing behavioral, say so in one line. Lead with any
    relaxation or removal instead of burying it under the token saving.

    ### Honesty note
    Close with these caveats, adapted to the case:
    - Label every quality claim predicted, measured, or verified. A score this pass assigned is
      predicted by definition, including the scorecard above.
    - Predicted scores and parity are single-pass estimates by the same model that wrote
      the variants, not measurements; small formatting changes alone are known to swing
      task accuracy, so treat the deltas as hypotheses.
    - To actually verify "fewer tokens, same results": run a paired eval (identical inputs
      per variant, pre-declared non-inferiority margin). The prompt-engineer prompt-evals
      guidance covers the method; promptfoo fits in CI.
    - If the prompt is a cached system prompt, repeat the cache-economics warning from
      the analysis.