references/heuristics_and_metaheuristics.md
# Heuristics and metaheuristics
## Table of contents
1. [When to use heuristics](#when-to-use-heuristics)
2. [Construction heuristics](#construction-heuristics)
3. [Local search](#local-search)
4. [Large neighborhood search](#large-neighborhood-search)
5. [Metaheuristics](#metaheuristics)
6. [Hybrid with exact methods](#hybrid-with-exact-methods)
7. [Quality measurement](#quality-measurement)
8. [OR-level simulation](#or-level-simulation)
## When to use heuristics
| Signal | Action |
|---|---|
| MIP gap flat after reasonable time | Switch or seed metaheuristic |
| Problem NP-hard at operational scale | Plan heuristic from start |
| Real-time re-optimization (< seconds) | Incumbent-first; partial solve |
| Need diverse solutions | Solution pool + perturbation |
Always retain **benchmark instances** where exact or strong bounds exist.
## Construction heuristics
| Pattern | Use |
|---|---|
| Nearest neighbor / greedy | Fast VRP or assignment start |
| Clarke-Wright savings | VRP routes |
| Earliest due date | Scheduling seed |
| Regret-k insertion | Richer VRP/insertion |
Document **determinism** (tie-breaking) for reproducible tests.
## Local search
| Move | Problem |
|---|---|
| 2-opt / 3-opt | TSP, route improvement |
| Swap / relocate | VRP, assignment |
| Shift one job | Scheduling |
| Or-opt chains | Route refinement |
**First improvement vs best improvement**—trade runtime vs quality.
## Large neighborhood search
1. Destroy part of solution (random, related, worst)
2. Repair with exact subroutine (MIP/CP) or greedy
3. Accept if better (or simulated annealing rule)
Strong for **VRP and scheduling** at scale when paired with OR-Tools or custom repair MIPs.
## Metaheuristics
| Method | Behavior | Notes |
|---|---|---|
| Genetic algorithm | Population, crossover, mutation | Encode feasibility carefully |
| Simulated annealing | Accept worse with cooling | Tune temperature schedule |
| Tabu search | Memory of recent moves | Aspiration criteria |
| GRASP | Randomized greedy + local search | Multiple iterations |
Avoid **tuning folklore** without validation on held-out instances.
## Hybrid with exact methods
| Pattern | Description |
|---|---|
| Matheuristic | Fix subset of integers; solve sub-MIP |
| Column generation + pricing heuristic | When exact pricing too slow |
| Branch-and-price with heuristic columns | Practical large instances |
| Warm start MIP | Inject heuristic incumbent |
Report **gap vs branch-and-bound bound** when available.
## Quality measurement
| Metric | Definition |
|---|---|
| Optimality gap | (UB − LB) / \|UB\| |
| Runtime | Wall clock to incumbent and to stop |
| Stability | Variance over seeds on same instance |
| Feasibility rate | % inputs where feasible solution returned |
Publish **Pareto** runtime vs quality curves when choosing production defaults.
## OR-level simulation
Use for:
- **Queueing**—M/M/c, G/G/1 approximations; staffing sensitivity
- **Discrete-event** lightweight models—verify plan under stochastic arrivals (not full sim platform)
- **Monte Carlo** over demand/cost scenarios when closed form unavailable
Do not conflate with **`simulation-software-engineer`** (runtime, sensors, replay engines).
references/linear_and_integer_optimization.md
# Linear and integer optimization
## Table of contents
1. [Model families](#model-families)
2. [LP workflow](#lp-workflow)
3. [MIP workflow](#mip-workflow)
4. [Formulation patterns](#formulation-patterns)
5. [Big-M discipline](#big-m-discipline)
6. [Valid inequalities and tightening](#valid-inequalities-and-tightening)
7. [Decomposition (conceptual)](#decomposition-conceptual)
8. [QP and conic notes](#qp-and-conic-notes)
## Model families
| Family | Variables | Typical use |
|---|---|---|
| LP | Continuous | Flows, blending, transport (fractional splits) |
| MIP | Integer/binary | Fixed costs, setup, yes/no assignments |
| QP | Continuous (+ quadratic) | Portfolio variance, distance squared (careful) |
| MILP | Mixed | Industry standard for planning |
## LP workflow
1. Build sparse constraint matrix or algebraic model
2. Check feasibility with Phase I or solver presolve
3. Solve; read duals only when **sure** model is pure LP (no degeneracy caveats documented)
4. Sensitivity: allow objective/rhs ranges where solver supports it
5. Report objective, dual summary (optional), binding constraints
## MIP workflow
1. Start from **LP relaxation**—bound quality predicts difficulty
2. Set **time limit** and **MIP gap** upfront; align with business SLO
3. Enable **presolve**, **cuts**, and **heuristics** (solver defaults often good)
4. Track **incumbent** improvement curve for tuning
5. If gap stalls—tighten formulation before raising time limit indefinitely
## Formulation patterns
| Pattern | Formulation sketch |
|---|---|
| Fixed charge | y_j ∈ {0,1}, x_j ≤ M y_j |
| Either-or | x ≤ M y, x ≥ m y (or SOS1) |
| Minimum batch | Σ x_i ≥ L y, x_i ≤ U y |
| Logical | Linearize with standard AND/OR templates |
| Piecewise linear | SOS2 or multiple binary segments |
Prefer **SOS and indicator constraints** when solver supports them—often numerically stabler than naive big-M.
## Big-M discipline
1. Derive M from **physical or logical bounds**, not 1e6 habit
2. Use **tightest valid M per constraint**, not one global constant
3. Test relaxation value—if binaries fractional at root, M likely loose
4. Consider **indicator constraints** (Gurobi/CPLEX) or OR-Tools literals
## Valid inequalities and tightening
| Technique | When |
|---|---|
| Cover inequalities | Knapsack-like rows |
| Clique cuts | Conflict graphs (scheduling, coloring) |
| Symmetry breaking | Identical machines/vehicles |
| Variable fixing | Dominated assignments from preprocessing |
| Bounds strengthening | Update LB/UB on variables from constraints |
Document any **manual cuts** so maintenance engineers understand binding logic.
## Decomposition (conceptual)
| Method | Idea | When |
|---|---|---|
| Benders | Master complicates, sub checks feasibility/cost | Large-scale facility, stochastic |
| Lagrangian | Relax coupling; dualize complicating constraints | Network + complicating side constraints |
| Column generation | Generate variables on the fly | Cutting stock, crew pairing |
| Dantzig-Wolfe | Block structure with master prices | Same family as column gen |
Prototype on small instances before committing to custom decomposition code.
## QP and conic notes
- Confirm **convexity** for global QP optimum
- Distance objectives often linearized for MILP (Manhattan) or handled in routing engines
- Second-order cone useful for robust norms—use when solver license includes conic
references/or_algorithm_developer_scope.md
# OR algorithm developer scope
## Table of contents
1. [Purpose](#purpose)
2. [Terminology](#terminology)
3. [In scope](#in-scope)
4. [Out of scope](#out-of-scope)
5. [Problem taxonomy](#problem-taxonomy)
6. [Roles and RACI](#roles-and-raci)
7. [Handoffs](#handoffs)
## Purpose
Define **operations research and optimization engineering**—formulating decision problems, implementing solver-backed models, and delivering production-grade optimization services.
This skill covers **mathematical modeling, algorithm selection, solver integration, and OR-specific production patterns**—not general software platforms, ML prediction pipelines, or warehouse/ERP product features.
## Terminology
| Term | Meaning |
|---|---|
| LP | Linear program—all objective and constraints linear in continuous variables |
| MIP | Mixed-integer program—some variables integer or binary |
| QP | Quadratic program—quadratic objective and/or constraints (often convex) |
| CP | Constraint programming—combinatorial search with global constraints |
| VRP | Vehicle routing problem—routes, capacity, time windows, pickups/deliveries |
| IIS | Irreducible infeasible subset—minimal conflicting constraint set |
| Incumbent | Best feasible solution found so far during search |
| MIP gap | (best bound − incumbent) / \|incumbent\| when minimizing |
| Warm start | Reuse prior solution or basis when re-solving perturbed model |
## In scope
| Area | Examples |
|---|---|
| Formulation | Objectives, hard/soft constraints, multi-objective scalarization, robust/stochastic hooks |
| Model classes | LP, MIP, QP, min-cost flow, assignment, VRP, scheduling, lot sizing |
| Algorithms | Simplex, interior point, branch-and-bound, cutting planes, column generation, Benders |
| Heuristics | Greedy construction, local search, large neighborhood search, GA/SA/TS when justified |
| OR simulation | Queueing networks, discrete-event at planning level, Monte Carlo over scenarios |
| Analysis | Sensitivity, shadow prices (where valid), IIS, benchmarking, gap reporting |
| Solvers | OR-Tools, Gurobi, CPLEX, HiGHS, PuLP, Pyomo (conceptual integration patterns) |
| Production | Optimization APIs, timeouts, incremental solve, logging, model versioning |
## Out of scope
| Topic | Route to |
|---|---|
| Predictive ML, deep learning, MLOps | `data-scientist` |
| SCM strategy, RFQ, supplier management without OR model | `supply-chain-manager` |
| WMS pick/wave/RF workflows | `wms-developer` |
| Physics/DES simulation platforms, SIL/HIL software | `simulation-software-engineer` |
| Generic CRUD backends and SaaS features | `senior-software-engineer` |
| Snowflake/dbt/BI mart design | `analytics-data-engineer` |
| Formal verification and proof obligations | `software-assurance-formal-methods-specialist` |
## Problem taxonomy
| Class | Typical decisions | Common methods |
|---|---|---|
| Allocation | Who gets what, when | LP, MIP, assignment |
| Routing | Sequences, tours, visits | VRP heuristics, MIP (small), OR-Tools routing |
| Scheduling | Start times, machines, jobs | CP, MIP, disjunctive formulations |
| Network | Flows, capacities, costs | LP, min-cost flow |
| Inventory / production | Lots, periods, setup | MIP, lot-sizing templates |
| Staffing | Shifts, coverage, skills | MIP, set partitioning |
## Roles and RACI
| Activity | OR engineer | Product / PM | Data eng | SWE platform | Domain SME |
|---|---|---|---|---|---|
| Problem framing | A | C | I | I | C |
| Formulation & prototype | A | I | C | I | C |
| Data pipeline for parameters | C | I | A | C | C |
| Production API & deploy | C | I | C | A | I |
| Solver licensing & capacity | C | I | I | A | I |
| Accept solution quality SLOs | C | A | I | C | C |
## Handoffs
- **To `data-scientist`** when the core task is prediction/forecast accuracy without explicit optimization over decisions
- **To `supply-chain-manager`** when deliverable is operating model, policy, or supplier process—not solver-backed plan
- **To `simulation-software-engineer`** when building a reusable simulator runtime (time stepping, sensors, replay)
- **To `senior-software-engineer`** when work is primarily application logic without OR formulation ownership
- **From `analytics-data-engineer`** when curated tables and metrics feed parameters; OR owns model and solve
references/problem_formulation_and_data.md
# Problem formulation and data
## Table of contents
1. [Formulation checklist](#formulation-checklist)
2. [Notation template](#notation-template)
3. [Hard vs soft constraints](#hard-vs-soft-constraints)
4. [Data preparation](#data-preparation)
5. [Validation rules](#validation-rules)
6. [Uncertainty hooks](#uncertainty-hooks)
7. [Common formulation errors](#common-formulation-errors)
## Formulation checklist
1. **Decision variables**—what is chosen (assign, route, schedule, produce)?
2. **State**—what is known vs decided each period?
3. **Objective**—single scalar; document weights for multi-criteria cases
4. **Constraints**—capacity, precedence, compatibility, time windows, minimum service
5. **Parameters**—demand, costs, travel times, capacities, yields (with units)
6. **Feasibility policy**—allow slack? penalty costs? reject infeasible inputs?
7. **Optimality target**—prove optimal, or accept gap/time limit?
## Notation template
Document before implementation:
```
Sets: I (items), J (locations), T (periods), K (vehicles)
Params: d_i (demand), c_ij (cost), Q_k (capacity), [τ_ij] (time)
Vars: x_ij ∈ {0,1} (assign i→j), y_kt ≥ 0 (inventory)
Objective: min Σ c_ij x_ij + holding costs
s.t. Σ_j x_ij = 1 ∀i (each item assigned once)
Σ_i d_i x_ij ≤ Q_j ∀j (capacity)
...
```
Keep **indices consistent** across data files, code, and reports.
## Hard vs soft constraints
| Type | Modeling pattern | When to use |
|---|---|---|
| Hard | Must hold; infeasible if violated | Safety, physical limits, regulations |
| Soft | Slack variable + penalty in objective | Preferences, target service levels |
| Elastic | Tiered penalties | Overtime, lateness bands |
Penalize slack in **objective units comparable to primary cost**—document penalty calibration.
## Data preparation
| Step | Action |
|---|---|
| Extract | Pull parameters from warehouse, ERP, GIS, or manual scenario files |
| Normalize | Consistent units (hours vs minutes, $ vs cents) |
| Index | Map business keys to model indices; keep bidirectional lookup tables |
| Aggregate | Roll up SKUs/locations when model size requires it—document loss |
| Impute | Only with explicit rules; flag imputed fields for sensitivity |
| Version | Tag scenario_id, effective_date, model_version on every solve |
## Validation rules
Run before every solve:
- **Dimensional analysis**—cost = rate × quantity; time matrices symmetric if required
- **Bounds**—capacities ≥ 0; demands non-negative unless returns modeled
- **Coverage**—every demand node has supply or penalty; every job has eligible resources
- **Graph checks**—no disconnected required arcs; unreachable customers flagged
- **Feasibility screen**—total demand ≤ total capacity (necessary, not sufficient)
## Uncertainty hooks
| Approach | Use when |
|---|---|
| Deterministic scenarios | Few discrete futures; solve each; compare |
| Stochastic programming | Here-and-now vs recourse; small scenario trees |
| Robust optimization | Uncertainty sets; protect worst-case within budget |
| Simulation outer loop | Complex dynamics; OR model inner step |
Route full **sim platform builds** to `simulation-software-engineer`; keep OR-level scenario loops lightweight.
## Common formulation errors
| Error | Symptom | Fix |
|---|---|---|
| Big-M too loose | Weak LP, slow MIP | Tighten M from problem structure |
| Strict inequality | Solver rejects or wrong | Use ≤ with ε or integer time grids |
| Double counting | Objective too low | Trace units through constraint blocks |
| Nonlinearity hidden | Local solver failure | Explicit linearization or conic/QP form |
| Missing coupling | Silly “optimal” plans | Link periods, routes, and inventory |
references/routing_scheduling_and_networks.md
# Routing, scheduling, and networks
## Table of contents
1. [Network flows and assignment](#network-flows-and-assignment)
2. [Vehicle routing (VRP)](#vehicle-routing-vrp)
3. [Scheduling](#scheduling)
4. [Resource allocation](#resource-allocation)
5. [Inventory and production planning](#inventory-and-production-planning)
6. [Method selection](#method-selection)
## Network flows and assignment
| Problem | Structure | Methods |
|---|---|---|
| Transportation | Bipartite supply/demand | LP, Hungarian (assignment) |
| Min-cost flow | Capacitated directed network | Network simplex, OR-Tools flow |
| Multi-commodity | Shared capacities | LP relaxation, MIP for integrality |
| Shortest path | One origin–destination | Dijkstra, A* with time windows |
**Check**: conservation of flow, capacity on arcs, cost sign convention.
## Vehicle routing (VRP)
| Variant | Extra structure |
|---|---|
| CVRP | Capacity per route |
| VRPTW | Time windows, service times |
| PDVRP | Pickup before delivery |
| Heterogeneous fleet | Multiple vehicle types/costs |
| Multi-depot | Depot choice per route |
**Exact MIP**: viable only for small instances; use for benchmarks.
**Metaheuristics / OR-Tools routing**: default for operational scale—document destroy/repair or search operators used.
**Output contract**: routes as ordered node lists, arrival times, load profiles, unassigned customers with reason codes.
## Scheduling
| Type | Decisions | Formulation notes |
|---|---|---|
| Job shop | Machine order per job | Disjunctive constraints; big-M or time-indexed |
| Flow shop | Same machine sequence | Simpler permutations |
| Parallel machines | Assign + order | Assignment + sequencing |
| Project scheduling | Precedence + resources | RCPSP; resource-constrained |
| Workforce | Shifts, skills, labor rules | Set covering/partitioning |
**Horizon discretization**: choose time buckets vs continuous—trade model size vs accuracy.
**Objective**: minimize makespan, tardiness Σ w_i T_i, or weighted completion.
## Resource allocation
- **Bipartite matching**: one-to-one assign with preferences/costs
- **Generalized assignment**: agents with capacity, tasks with demand—MIP
- **Fairness**: max-min or equity constraints—may need extra variables or multi-objective scalarization
Coordinate with **product SLOs**—explain trade-off between cost optimality and fairness.
## Inventory and production planning
| Model | Elements |
|---|---|
| Economic order quantity | Closed form; baseline only |
| Multi-period lot sizing | Setup binary, inventory balance, capacity |
| Capacitated production | Ramp limits, overtime variables |
| BOM explosion | Multi-level; link to `supply-chain-manager` for policy, OR for solve |
**Link periods**: inventory_t = inventory_{t-1} + production − demand.
## Method selection
| Scale / structure | Prefer |
|---|---|
| Pure network, continuous | LP / min-cost flow |
| Small combinatorial | MIP or CP |
| Large routing | Specialized VRP engine + local search |
| Large scheduling | CP (OR-Tools CP-SAT) or decomposition |
| Need proven gap | MIP with time limit; report gap |
Route **warehouse execution software** to `wms-developer`; OR may output **plans** (waves, routes) as inputs, not WMS code.
references/solver_integration_and_production.md
# Solver integration and production
## Table of contents
1. [Solver landscape](#solver-landscape)
2. [Selection criteria](#selection-criteria)
3. [Model lifecycle](#model-lifecycle)
4. [API and service patterns](#api-and-service-patterns)
5. [Timeouts and fallbacks](#timeouts-and-fallbacks)
6. [Warm starts and incremental solve](#warm-starts-and-incremental-solve)
7. [Infeasibility diagnosis](#infeasibility-diagnosis)
8. [Sensitivity and reporting](#sensitivity-and-reporting)
9. [Observability](#observability)
10. [Licensing and deployment](#licensing-and-deployment)
## Solver landscape
| Stack | Strengths | Typical interface |
|---|---|---|
| OR-Tools | Routing, CP-SAT, free tier | Python, C++ |
| Gurobi | Fast MIP/LP, tuning | Python, PuLP, Pyomo |
| CPLEX | Enterprise MIP, CP | Same |
| HiGHS | Open-source LP/MIP | PuLP, Pyomo |
| PuLP | Modeling → multiple backends | Python |
| Pyomo | Algebraic modeling, decomposition hooks | Python |
Treat solver choice as **non-functional requirement**—license, support, and performance on *your* model class.
## Selection criteria
| Criterion | Question |
|---|---|
| Problem fit | Routing native? CP? Conic? |
| Scale | Variables, constraints, binary count |
| Gap SLO | Need proven optimal or 1% gap in 60s? |
| License | Cloud, container, academic, core count |
| Team skill | Existing Pyomo vs raw API |
| Determinism | Same seed → same incumbent? |
## Model lifecycle
1. **Version** formulation (git tag) separate from code
2. **Serialize** instance files (JSON, LP, MPS) for reproducibility
3. **CI**: small golden instances—objective within tolerance, feasible
4. **Staging**: full-size nightly with time limits
5. **Production**: pinned solver version; monitor regressions
## API and service patterns
| Pattern | Use |
|---|---|
| Sync solve | Interactive planning UI (< few minutes) |
| Async job | Large MIP; poll status; store incumbent |
| Batch | Overnight scenario packs |
| Incremental | Real-time dispatch with warm start |
**Response payload**: status, objective, gap, runtime, solution, dual summary (optional), warnings, model_version.
Validate inputs **before** solver call—return 400 with structured errors, not opaque solver crashes.
## Timeouts and fallbacks
| Policy | Behavior |
|---|---|
| Time limit | Return best incumbent + gap |
| No incumbent | Return infeasible or “no solution” with diagnostics |
| Degraded mode | Heuristic-only path if MIP exceeds budget |
| Previous plan | Serve last feasible if new solve fails (document staleness) |
Never block HTTP workers unbounded—thread pool or job queue for long solves.
## Warm starts and incremental solve
- **MIP start**: inject prior x values; verify feasibility
- **LP basis** (advanced): speed re-solve after small rhs changes
- **Rolling horizon**: fix early periods, optimize tail
- **Real-time**: limit changed variables; short time limit
Log whether warm start **improved time to first incumbent**.
## Infeasibility diagnosis
| Step | Tool / action |
|---|---|
| 1 | Presolve infeasible → check data validation |
| 2 | IIS (Gurobi/CPLEX) → minimal conflict set |
| 3 | Elastic mode / slack on constraint groups | Rank relaxations |
| 4 | Manual bisect | Disable constraint families |
Deliver **business-readable conflict**—e.g., “capacity week 12 + minimum service” not only row IDs.
## Sensitivity and reporting
- **Objective coefficients**: allowable increase/decrease (LP)
- **RHS shadow prices**: interpret only for valid LP segments
- **Scenario compare**: side-by-side objectives and key decisions
- **Benchmark table**: method, gap, time, nodes (MIP)
## Observability
| Metric | Purpose |
|---|---|
| solve_duration_ms | SLO tracking |
| mip_gap | Quality |
| incumbent_found | Reliability |
| infeasible_count | Data/model health |
| solver_status | Failure taxonomy |
Alert on **gap regression** or **infeasibility spike** after deploy.
## Licensing and deployment
- Run license server or cloud token per vendor docs
- Pin **solver version** in container images
- Isolate **CPU and memory** limits for solve workers
- Do not embed license secrets in repos—use env/secret store
Coordinate with **`senior-software-engineer`** for service mesh, auth, and deployment; OR owns model correctness and solve SLOs.
SKILL.md
---
name: operations-research-algorithm-developer
description: |
Formulate and implement operations research optimization models—LP, MIP/QP, constraint programming,
network flows, assignment, VRP, scheduling, resource allocation, inventory/production planning;
heuristics and metaheuristics; sensitivity and infeasibility diagnosis; solver integration
(OR-Tools, Gurobi, CPLEX, HiGHS, PuLP, Pyomo); production OR APIs (timeouts, warm starts).
Use for operations research, OR engineer, optimization model, linear programming, mixed integer
programming, MIP, VRP, vehicle routing, scheduling optimization, OR-Tools, Gurobi, constraint
programming, resource allocation optimization, infeasible model, metaheuristic—not ML prediction
(data-scientist), SCM strategy without optimization math (supply-chain-manager), WMS features
(wms-developer), simulation platforms (simulation-software-engineer), generic backend
(senior-software-engineer), dbt/warehouse (analytics-data-engineer).
---
# Operations Research Algorithm Developer
## When to Use
- Frame a **decision problem** as an optimization model—objectives, decisions, constraints, parameters, uncertainty
- Build **LP, MIP, QP, or constraint programming** formulations for planning and allocation
- Model **network flows**, **assignment**, **routing (VRP)**, **scheduling**, and **resource allocation**
- Design **inventory and production planning** models (lot sizing, capacity, multi-period)
- Select **exact vs heuristic** methods—branch-and-bound, column generation, decomposition, metaheuristics
- Run **sensitivity analysis**, **infeasibility diagnosis**, and **benchmarking** (optimality gap, runtime)
- Integrate **solvers** conceptually—OR-Tools, Gurobi, CPLEX, HiGHS, PuLP, Pyomo—and production patterns
- Prepare **input data**, validate units, and enforce **constraint modeling discipline**
- **Productionize** OR services—APIs, timeouts, warm starts, incremental solves, solution pools
## When NOT to Use
- **General ML predictive modeling**, feature engineering, A/B tests, or MLOps → `data-scientist`
- **Supply chain strategy**, RFQ, supplier scorecards, or inventory policy without optimization math → `supply-chain-manager`
- **WMS workflows**—waves, pick paths, RF scanning, ERP/WMS integration → `wms-developer`
- **Simulation platform software**—physics engines, SIL/HIL rigs, deterministic replay frameworks → `simulation-software-engineer`
- **Generic backend**, CRUD APIs, or cloud microservices without OR models → `senior-software-engineer`
- **Analytics warehouse**, dbt marts, dimensional modeling, BI semantic layers → `analytics-data-engineer`
- **Formal proof obligations** or certified assurance cases → `software-assurance-formal-methods-specialist`
## Related skills
| Need | Skill |
|---|---|
| ML prediction, experimentation, MLOps | `data-scientist` |
| SCM sourcing, forecast process, supplier QBRs | `supply-chain-manager` |
| Warehouse management application logic | `wms-developer` |
| DES/physics sim platforms, digital twins | `simulation-software-engineer` |
| Enterprise application and API engineering | `senior-software-engineer` |
| dbt, warehouse modeling, BI pipelines | `analytics-data-engineer` |
| Executive dashboards and KPI storytelling | `bi-analyst` |
| Service SLOs and production incident response | `site-reliability-engineer` |
## Core Workflows
### 1. Scope and problem class
Clarify decision horizon, granularity, optimality requirements, and handoffs to product/engineering.
**See `references/or_algorithm_developer_scope.md`.**
### 2. Formulation and data
Define sets, parameters, variables, objective, constraints; validate data and units.
**See `references/problem_formulation_and_data.md`.**
### 3. Linear and integer optimization
LP/MIP/QP structure, big-M discipline, tightening, decomposition hooks.
**See `references/linear_and_integer_optimization.md`.**
### 4. Routing, scheduling, and networks
VRP variants, job-shop and resource scheduling, min-cost flow and assignment patterns.
**See `references/routing_scheduling_and_networks.md`.**
### 5. Heuristics and metaheuristics
When to leave exact solvers; construction, local search, GA/SA/TS; solution quality metrics.
**See `references/heuristics_and_metaheuristics.md`.**
### 6. Solver integration and production
Solver choice, model lifecycle, APIs, timeouts, warm starts, monitoring, and failure modes.
**See `references/solver_integration_and_production.md`.**
## Outputs
- **Problem formulation brief**—decisions, objective, hard vs soft constraints, assumptions
- **Mathematical model**—notation, formulation, linearization notes, parameter catalog
- **Data specification**—required inputs, validation rules, unit checks, scenario keys
- **Solution report**—objective, gap, runtime, binding constraints, sensitivity highlights
- **Infeasibility / IIS summary**—conflicting constraint groups and remediation options
- **Implementation outline**—solver stack, API contract, timeout and fallback policy
- **Benchmark table**—instances, gap %, time, memory, method comparison
## Principles
- **Formulate before coding**—write the math (even briefly) before choosing a solver API
- **Separate data from model**—parameters drive constraints; avoid hard-coding scenario logic in solver calls
- **Prefer tight formulations**—fewer binaries, tighter bounds, and valid inequalities over brute force
- **Measure optimality**—report gap, bounds, and time limits; never imply optimality without proof
- **Diagnose infeasibility systematically**—IIS, elastic filters, or constraint relaxation ladders
- **Production OR needs SLOs**—timeouts, warm starts, and feasible incumbent policies are part of the design
- **Route non-OR work to peers**—ML, WMS features, and sim platforms are not substitutes for correct OR scope
## When to load references
| Topic | Reference |
|---|---|
| Role scope, boundaries, RACI | `references/or_algorithm_developer_scope.md` |
| Sets, parameters, validation | `references/problem_formulation_and_data.md` |
| LP, MIP, QP, tightening | `references/linear_and_integer_optimization.md` |
| VRP, scheduling, networks | `references/routing_scheduling_and_networks.md` |
| Heuristics, metaheuristics | `references/heuristics_and_metaheuristics.md` |
| Solvers, APIs, production | `references/solver_integration_and_production.md` |