/prompt-optimization

name: prompt-optimization
description: Improves LLM-facing context while preserving intent, execution boundaries, and proportional work. Use when creating or reviewing prompts, agent definitions, skill definitions, or other instructions for an LLM.

Prompt Optimization Skill

Purpose

Improve prompts while preserving user intent.

Core Principles

1. **Procedural Gates**: Complete analysis, optimization, and balance in order. Each phase has observable pass conditions that control the next transition. 2. **Intent Preservation**: Record the original requirements before changing wording, structure, context, constraints, or examples. 3. **Necessary and Sufficient Context**: Include the information needed for a decision, action, or verification result. Condense or omit information that does not affect one of them. 4. **Minimal Sufficient Work**: Classify discovered possibilities as candidates. Add work only when it changes the outcome, protects a required boundary, serves a real consumer, or supplies necessary proof. 5. **Traceable Changes**: Connect every change to a finding or project-specific source. 6. **Self-Contained Execution**: Require no temporary artifacts or additional agents.

Required References

Load references at the phase where their rules become necessary:

| Phase | Condition | Required reference | |---|---|---| | Analysis | Every prompt | `references/patterns.yaml` | | Analysis | Target is a SKILL.md, agent, or skill reference | `references/skills.md` | | Balance | Every prompt | `references/execution-quality.yaml` |

Record the loaded path and covered rule IDs in the phase's `reference_coverage`. A phase passes only when its required references and rule coverage are present.

Output Mode

Select the output mode before analysis. An explicit `output_mode` of `interactive` or `machine` takes priority; for any other value, ask the caller to choose one. When it is absent, use Machine mode only if the caller explicitly requests the `Machine Output Contract` as the response format; otherwise use Interactive mode. Apply the same rule to human and LLM callers.

Keep `output_mode` outside the target prompt and `analysis.original_prompt`.

Pattern Detection

Evaluate every pattern and record `issue`, `already_satisfied`, or `not_applicable`.

| Priority | ID | Pattern | Decision goal | |---|---|---|---| | P1 | BP-001 | Negative Instructions | Lead with the required behavior; retain explicit prohibitions for narrow irreversible boundaries | | P1 | BP-002 | Vague Instructions | Resolve an outcome-relevant ambiguity with the least-restrictive sufficient criterion | | P1 | BP-003 | Missing Output Format | Define the shape needed by the output consumer | | P1 | BP-009 | Unbounded Work Generation | Prevent technically valid possibilities from becoming unnecessary work | | P2 | BP-004 | Unstructured Prompt | Make priority and relationships visible when structure reduces ambiguity | | P2 | BP-005 | Missing or Excess Context | Supply decision-sufficient context without distractors or duplication | | P2 | BP-006 | Missing or Excess Procedural Control | Keep required gates without prescribing reversible routes | | P3 | BP-007 | Unnecessary or Biased Examples | Use examples only for non-obvious mappings, then control their bias | | P3 | BP-008 | Missing Uncertainty Handling | Define evidence, escalation, and stopping behavior for unresolved inputs |

Gated 3-Step Flow

Maintain one complete phase-state object in the current invocation. Complete each phase and its gate before generating the next phase; use the transition table as the control rule. Serialize the object only in Machine mode.

Step 1: Analysis

1. Load the analysis references required for the target type. 2. Preserve the original prompt verbatim. 3. Record the prompt's intended outcome and requirements that later phases must preserve. 4. Evaluate BP-001 through BP-009. Record every distinct issue in `findings` with a unique `finding_id`, pattern, severity, location, and quoted evidence. A BP-002 finding represents one decision required by the intended outcome whose plausible interpretations would materially change correctness, requested scope, downstream usability, or verification. 5. Record missing inputs under `unresolved_inputs`.

`analysis_gate` passes when:

• all required analysis references are covered;
• BP-001 through BP-009 each have one summary whose `finding_ids` match its findings;
• every distinct issue has one finding with evidence, location, pattern, and severity;
• preservation requirements are explicit; and
• no unresolved input prevents a faithful optimization.

Step 2: Optimization

Start this step when `analysis_gate.status` is `pass`.

1. Resolve every finding as `applied` or `skipped` with a reason. For BP-002, choose the least-restrictive clarification that supplies the required precision and base the reason on its precision contribution and constraint cost. 2. Apply Structural and Context Addition changes that improve task execution. 3. Consolidate redundant changes and preserve requirements recorded in Step 1. 4. Produce the candidate optimized prompt.

`optimization_gate` passes when:

• every finding has exactly one resolution;
• every change traces to a finding or named project source;
• all preservation requirements remain represented;
• added constraints remove a real ambiguity or protect a real requirement;
• added obligations affect the outcome, a required boundary, a real consumer, or necessary proof; and
• every applied BP-002 clarification identifies an observable precision contribution and preserves the valid solutions allowed by the original intent.

Step 3: Balance

Start this step when `optimization_gate.status` is `pass`.

1. Load `references/execution-quality.yaml`. 2. Evaluate intent preservation, decision sufficiency, information density, constraint necessity, work proportionality, and traceability. 3. Apply balance adjustments and record each adjust