text-to-optimization

name	text-to-optimization
description	End-to-end: convert natural language -> IR -> (Markdown formulation + Julia JuMP code) -> solve (HiGHS) and write results back into the Markdown.
argument-hint	[paste problem statement]
allowed-tools	Read, Write, Bash(julia *)
metadata	{"domain":"math-modeling","interaction-language":"en"}

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"

4. 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.

5. 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

Reference	When to read
references/sets.md	Set schema, indexing, and membership semantics
references/parameters.md	Parameter schema, indexed value encoding, and parameter lookups
references/objective.md	Objective schema, degree limits, and common modeling patterns
references/expr-ast.md	Canonical ExprAST node forms and validation/runtime constraints
references/variables.md	Canonical variable schema and lifecycle (IR -> validation -> JuMP -> outputs)
references/constraints.md	Canonical constraint schema and lifecycle (IR -> validation -> JuMP -> outputs)
references/solver-hints.md	solver_hints semantics
references/advanced-usage.md	Sysimage and step-by-step script mode