text-to-optimization

Use This Skill When

• •The user gives a linear/quadratic optimization word problem.
• •The requested output is model formulation + solver result + reproducible JuMP code.
• •HiGHS is acceptable as the solver.
• •The user asks for step-by-step diagnostics, solver-hint tuning, or startup-latency optimization for this same pipeline.

Do Not Use This Skill When

• •The task is not an optimization model (for example: data cleaning, translation, UI coding).
• •The user needs nonlinear constraints, indicator constraints, piecewise-linear functions, or multi-objective optimization.
• •The user only wants conceptual discussion with no model/code generation.

Routing Examples

• •Trigger: "Maximize weekly profit with limited labor and machine hours."
• •Trigger: "Minimize shipping cost with plant capacities and customer demands."
• •Do not trigger: "Debug this React hydration error."
• •Do not trigger: "Translate this paragraph to English."

Workflow

1. •Ask only minimal clarifying questions if critical data is missing.
2. •Construct IR JSON in memory with schema assets/ir-schema.json.
   • •Extract all numeric data from the problem as named parameters. Use {"param": "name"} references for those values.
   • •{"const": ...} is allowed for algebraic literals and derived coefficients (for example 0, 1, -1, or 1.5 after linearization) that are not standalone problem inputs.
   • •Set top-level question to the original user problem statement. If the prompt is poorly structured, you may rewrite it into a clean, well-structured statement without changing any numeric values or meaning.
   • •For every variable, set vartype explicitly (Continuous, Integer, or Binary). Never rely on default vartype.
   • •Variable typing rule: use Integer for countable decisions (batches, trips, boxes, workers, patients, operating days) unless divisibility is explicitly stated; use Binary for yes/no decisions; use Continuous only when the quantity is explicitly divisible.
   • •If user text is ambiguous and clarifying is disallowed, prefer conservative count semantics (Integer) for count-like decisions and record the assumption explicitly.
   • •Prefer compact indexed constraint families in IR: encode "for each index" as outer {"op":"sum", ...} quantifiers whose terminal body is a comparison node, instead of manually expanding one constraint per index element.
   • •For compact constraint families, keep constraints[].name as a base label with no indices (no [...]). Indexing belongs in the quantified sum wrapper, not in the constraint name.
   • •Include assumptions and missing_info.
3. •Bootstrap Julia environment if needed:

SKILL_ROOT=.agents/skills/text-to-optimization
julia "$SKILL_ROOT/scripts/bootstrap.jl"

1. •Run unified pipeline (validate -> export -> solve -> append results):

SKILL_ROOT=.agents/skills/text-to-optimization
julia "$SKILL_ROOT/scripts/run_pipeline.jl" \
  --md-output workspace/<name>.md \
  --jl-output workspace/<name>.jl <<'EOF'
<IR_JSON>
EOF

• •Exit codes: 0 success, 1 solve failure, 2 validation failure.
• •Use --skip-validate only if IR was already validated.

1. •Reply with a short confirmation listing generated files.

Do NOT output IR JSON in chat.

Minimum IR Skeleton

• •Root schema is strict (additionalProperties: false): unknown top-level fields are rejected.
• •Required root fields: version, problem_type, sense, variables, objective, constraints.
• •variables must be non-empty (minItems: 1).
• •In practice, set vartype explicitly for each variable.

{
  "$schema": "assets/ir-schema.json",
  "version": "0.2.0",
  "problem_type": "optimization",
  "sense": "max",
  "sets": {},
  "parameters": {},
  "variables": [
    {
      "name": "x",
      "domain": "Nonnegative",
      "vartype": "Integer",
      "description": "Count decision variable (example)"
    }
  ],
  "objective": {
    "expr_ast": {"var": "x"},
    "meaning": "Maximize x"
  },
  "constraints": []
}

• •Canonical complete example: assets/examples/lp-production.json.

Quick Smoke Test

SKILL_ROOT=.agents/skills/text-to-optimization
julia "$SKILL_ROOT/scripts/run_pipeline.jl" \
  --md-output workspace/lp_production.md \
  --jl-output workspace/lp_production.jl < "$SKILL_ROOT/assets/examples/lp-production.json"

• •Expected: exit code 0, workspace/lp_production.md, and workspace/lp_production.jl.

Output Files

• •workspace/<name>.md: model formulation + appended solver results.
• •workspace/<name>.jl: deterministic JuMP + HiGHS model code.

Naming: descriptive snake_case (for example production_planning, vehicle_routing, portfolio_optimization).

Naming Convention

Use standard mathematical symbols for sets, parameters, and variables. Keep constraint names as short English role labels.

• •Sets: uppercase single letter or short abbreviation (I, J, P, K). Distinguish similar sets with subscripts (S_1, S_2).
• •Parameters: single letter, optionally with a short subscript (c, a, b, T, M, alpha, c_1, D_0). Avoid multi-word underscored names like D_req or m_min — prefer a single letter with a clear description.
• •Variables: lowercase single letter (x, y, z, w). Use different letters for distinct variable groups.
• •Constraints: meaningful short English labels that reflect the constraint's role (demand, capacity, budget, ratio, balance, flow). Do not embed indices in name (avoid demand[j], demand[1], etc.); represent families via the quantified sum wrapper instead. Avoid generic con_1, con_2.
• •description fields are strongly recommended for sets, parameters, and variables; they improve generated Markdown readability. Use meaning for constraints.
• •unit field is optional on parameters. Use it only when it disambiguates scale/dimension, and avoid ambiguous abbreviations.

For sets/parameters/variables, do NOT use descriptive English names like profit, machine_time, or material_capacity; keep semantics in description.

Numeric values from the problem statement should normally be named parameters so the formulation stays parametric; keep {"const": ...} for algebraic literals/derived coefficients.

Determinism Rules

• •Always validate IR before solving/exporting.
• •Use only scripts under scripts/.
• •Solver must be HiGHS.
• •validate_ir.jl, export_md_julia.jl, solve_jump.jl read IR JSON from stdin.
• •append_results_md.jl reads solver-result JSON from stdin and appends into existing Markdown.

Current Limits

• •Constraints must be linear (degree <= 1).
• •Objective supports up to quadratic terms (degree <= 2).
• •No indicator constraints, piecewise-linear functions, or multi-objective optimization.

References