diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 25d273e..a2ba774 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -239,6 +239,15 @@ "strict": false, "description": "Interact with Atlassian Confluence from the terminal: list spaces, browse pages, view page content, search with CQL, and create pages. Use when the user mentions Confluence, a space key (e.g. DEV), or asks about documentation, wiki pages, space content, or knowledge base articles. Do not use this skill for unrelated requests; route to the nearest named specialist." }, + { + "name": "constrained-optimization", + "source": "./", + "skills": [ + "./constrained-optimization" + ], + "strict": false, + "description": "Define, compare, and audit constrained optimization decisions with explicit variables, units, hard and soft constraints, feasibility, Pareto tradeoffs, and honest solver evidence. Do not use for statistical modeling or ML fitting, which belong to data-scientist or ml-engineering, or for operating a named solver." + }, { "name": "crewai", "source": "./", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 5d9ce8c..175195c 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -44,6 +44,7 @@ "./color-management", "./conditional-customer-success", "./confluence-cli", + "./constrained-optimization", "./crewai", "./crm", "./crowdsec", diff --git a/README.md b/README.md index 139c7ed..3c15a0e 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,10 @@ A conditional skill for products with recurring human relationships — success Atlassian Confluence from the terminal. List spaces, browse pages, view content with body extraction, search with CQL, and create pages. Same API token as Jira. +### [constrained-optimization](constrained-optimization/SKILL.md) + +Formulate and evaluate constrained allocation, routing and scheduling decisions with explicit feasibility, objective units, exact or heuristic baselines, repeatable comparisons and honest solver-status evidence. + ### [crewai](crewai/SKILL.md) An expert-level skill for building **role-based multi-agent teams** with CrewAI. Agents are defined as Roles with Goals and Backstories; crews are composed with sequential or hierarchical workflows. diff --git a/constrained-optimization/README.md b/constrained-optimization/README.md new file mode 100644 index 0000000..83fed1f --- /dev/null +++ b/constrained-optimization/README.md @@ -0,0 +1,33 @@ +# Constrained optimization + +Make optimization decisions that remain valid when constraints, tradeoffs, and solver limits matter. + +## Why Install This Skill + +Optimization results are easy to misread: a lower score may violate a hard limit, a timeout may be mistaken for infeasibility, and an average from one random run may not survive repetition. This skill gives an agent a disciplined way to state the problem before choosing a method. + +It produces reviewable formulation and solution-audit records. The workflow separates feasible candidates from infeasible ones, preserves exact-solver bounds and gaps, and makes multiobjective and stochastic tradeoffs explicit. + +## What You Get + +| Directory | Purpose | +|---|---| +| `SKILL.md` | Decision workflow, boundaries, and routing | +| `references/` | Formulation, solver evidence, Pareto, robustness guidance, and primary-source index | +| `templates/` | Formulation and solution-audit records | +| `evals/` | Quality cases for common optimization failures | + +## Quick Start + +Start with `SKILL.md`, then fill `templates/formulation-record.md` before selecting a solver. Use `templates/solution-audit.md` to independently verify the returned candidate. + +## Triggers + +- Formulating a constrained optimization problem +- Comparing exact methods, heuristics, or stochastic search +- Reviewing feasibility, optimality gaps, or timeout claims +- Choosing among Pareto tradeoffs or objective priorities + +## Requirements + +No solver, API key, or runtime is required. Named solver operation and statistical modeling remain with their respective skills. diff --git a/constrained-optimization/SKILL.md b/constrained-optimization/SKILL.md new file mode 100644 index 0000000..45f0f2f --- /dev/null +++ b/constrained-optimization/SKILL.md @@ -0,0 +1,36 @@ +--- +name: constrained-optimization +description: >- + Define, compare, and audit constrained optimization decisions with explicit + variables, units, hard and soft constraints, feasibility, Pareto tradeoffs, and + honest solver evidence. Do not use for statistical modeling or ML fitting, which + belong to data-scientist or ml-engineering, or for operating a named solver. +license: MIT +--- + +# Constrained optimization + +Use this methodology to turn an optimization request into a defensible decision record. + +## Workflow + +1. **Frame the decision.** Name the decision maker, feasible action window, variable domains (continuous, integer, categorical, binary), bounds, units, and whether each variable is controllable. +2. **State objectives.** Write objective direction, units, aggregation, baseline, and acceptable tradeoffs. Keep multiple objectives separate until a decision maker chooses weights, lexicographic priority, epsilon constraints, or a Pareto review. +3. **Classify constraints.** Mark each as hard (must hold), soft (preference with an explicit penalty or relaxation), or informational. Define equality/inequality tolerance, feasibility predicate, and how violations are measured. Never hide a hard violation in a penalty score. +4. **Establish baselines.** Validate a known feasible incumbent, a simple exact or bounded baseline where available, and a heuristic baseline when exact solving is impractical. State what each baseline proves and does not prove. +5. **Choose the method.** Match solver family to domains, smoothness, scale, and proof needs. An exact solver can establish optimality or a bound when its status and gap support it; a heuristic supplies a candidate and empirical evidence. Do not call timeout or unknown an infeasible result. +6. **Run a fair comparison.** Fix an objective/constraint implementation, feasibility checker, compute budget, stopping rule, and reporting schema. For stochastic methods, use equal budgets and declared seeds/repeats. Keep solver configuration separate from the formulation. +7. **Independently validate.** Recompute objective and every constraint from the returned decision using an independent implementation or checker. Report feasible-best, violation magnitude, bound/gap, status, runtime, and unresolved unknowns separately. +8. **Decide and monitor.** Select a feasible solution or Pareto set with the tradeoff rationale, sensitivity/robustness evidence, owner, and rollback/re-optimization trigger. Record “infeasible under these constraints” only when infeasibility is proven or independently certified. + +## Routing and exit + +Load `references/formulation-and-evidence.md` for formulation, feasibility, solver status, bounds/gaps, and comparison rules. Load `references/multiobjective-and-robustness.md` for Pareto decisions and stochastic sensitivity. Use [the formulation record](templates/formulation-record.md) to define the problem before solving, and [the solution audit](templates/solution-audit.md) to verify a returned candidate. + +This skill owns decision formulation and evidence. Route statistical estimation, causal questions, and uncertainty models to `data-scientist`; route ML hyperparameter/model training optimization to `ml-engineering`; route operation of a named solver or cloud service to its tool skill. Stop when variables, objective units, hard constraints, feasibility checker, or budget are undefined. Complete when the formulation and solution audit record the decision, supporting evidence, unresolved limits, and owner. + +For the official solver-result references and their version/applicability limits, read [the source index](references/source-index.md). + +## When not to use + +Do not use this skill for inferential statistics, causal inference, or statistical model fitting. Do not use it for ML training/model selection methodology or for solver-specific installation and runbooks. diff --git a/constrained-optimization/evals/evals.json b/constrained-optimization/evals/evals.json new file mode 100644 index 0000000..2fe4bfb --- /dev/null +++ b/constrained-optimization/evals/evals.json @@ -0,0 +1,13 @@ +{ + "schema_version": 1, + "skill_name": "constrained-optimization", + "evals": [ + {"id":"hard-constraint-violation","prompt":"Candidate A has objective 10 but exceeds a hard safety limit; candidate B has objective 12 and is feasible. Decide.","expected_output":"Reject A and compare feasible candidates only, reporting the violation and independent feasibility check.","assertions":["The response rejects a candidate that violates a hard constraint","The response does not hide the violation in a penalty score","The response compares feasible-best results separately","The response requires independent constraint recomputation"]}, + {"id":"objective-units-direction","prompt":"A team says optimize cost, quality, and latency but gives no units or direction. What must be clarified?","expected_output":"Require explicit objective direction, units, aggregation, baseline, thresholds, and decision priorities before solver selection.","assertions":["The response requires units for every objective","The response requires minimize or maximize direction","The response requires aggregation and baseline","The response requires explicit priorities or tradeoff rule"]}, + {"id":"pareto-tradeoff","prompt":"Two feasible solutions trade lower cost for higher quality and lower latency. There is no agreed weighting. Recommend a decision process.","expected_output":"Identify nondominated candidates, report units and residuals, then obtain weights, lexicographic priorities, or epsilon limits from the decision maker.","assertions":["The response identifies Pareto or nondominated candidates","The response does not invent a scalar weighting","The response reports constraint status and objective units","The response requires a decision-maker tradeoff rule"]}, + {"id":"stochastic-equal-budget","prompt":"A heuristic beats the baseline once with a lucky seed but uses twice the compute budget. How should it be evaluated?","expected_output":"Repeat under equal budgets with declared or paired seeds, report distribution and failure rate, and avoid selecting on the best run alone.","assertions":["The response enforces equal evaluation budgets","The response requires declared seeds or repeat protocol","The response reports spread or distribution and failure rate","The response rejects best-run-only evidence"]}, + {"id":"unknown-vs-infeasible","prompt":"A CP solver stops at its time limit without a solution and reports UNKNOWN. Can we claim the constraints are infeasible?","expected_output":"No. Preserve UNKNOWN as unresolved; claim infeasibility only with a proof or explicit infeasible status, and record the limit and next action.","assertions":["The response does not call UNKNOWN infeasible","The response distinguishes timeout from proven infeasibility","The response records solver status and limit","The response proposes a bounded follow-up or labels the result unresolved"]}, + {"id":"bound-gap-interpretation","prompt":"An exact solver returns a feasible incumbent and a nonzero optimality gap at timeout. What can be claimed?","expected_output":"Report the feasible incumbent and bound/gap, but do not claim global optimality; include tolerance, budget, and unresolved optimality.","assertions":["The response reports the feasible incumbent separately from the bound","The response interprets the nonzero gap as lack of proof of optimality","The response includes timeout/budget and tolerance","The response avoids claiming global optimum"]}, + {"id":"independent-feasibility-audit","prompt":"The solver says success, but its objective and constraints were computed by the same callback code. What release evidence is missing?","expected_output":"Recompute objectives, domains, residuals, and feasibility with an independent checker and retain both raw solver and audit outputs.","assertions":["The response requires an independent feasibility implementation","The response recomputes objective and every hard constraint","The response checks domains and tolerances","The response retains raw and audit evidence"]} + ] +} diff --git a/constrained-optimization/references/formulation-and-evidence.md b/constrained-optimization/references/formulation-and-evidence.md new file mode 100644 index 0000000..aeb524f --- /dev/null +++ b/constrained-optimization/references/formulation-and-evidence.md @@ -0,0 +1,19 @@ +# Formulation and solver evidence + +## Formulation checklist + +Write the problem in a unit-consistent form: decision vector and domains; objective(s) with minimize/maximize direction; hard constraints and tolerances; soft constraints and penalty units; data/configuration revision; and a feasibility predicate that can be run independently. Normalize objectives only when the scale and reference points are documented. A penalty coefficient must have an interpretable relationship to the objective and cannot make an unacceptable hard violation “worth it.” + +Use a feasible incumbent whenever possible. If no feasible point is known, run a feasibility phase or report that the search has not established feasibility. A candidate with a better raw objective but any hard violation is not a solution to the stated problem. + +## Method evidence + +Use an exact or certifying baseline when the formulation and scale allow it. Report solver status, incumbent objective, bound, gap definition, time/memory limit, and tolerance. A feasible incumbent with a nonzero gap is evidence of a candidate and a bound, not proof of global optimality. A heuristic or metaheuristic should report initialization, seed/repeat policy, budget, best feasible value, violation summary, and comparison against the same checker and budget. + +Solver status is evidence, not prose. For example, SciPy’s optimization results expose `success` and a termination `message`, while its linear-programming tutorial demonstrates checking constraint residuals independently. OR-Tools CP-SAT distinguishes `OPTIMAL`, `FEASIBLE`, `INFEASIBLE`, `MODEL_INVALID`, and `UNKNOWN`; `UNKNOWN` includes stopping before infeasibility is proven. Preserve that distinction in any adapter. See [the source index](source-index.md) for direct official references, versions, and transfer limits. + +## Fair comparison and validation + +Freeze the formulation, data, checker, hardware class, wall-clock or evaluation budget, and stopping rule. Compare methods on the same feasible-best definition. For stochastic methods, use paired seeds or a declared repeat design and report the distribution, not only the best run. Validate returned decisions with an independent implementation that recomputes units, bounds, equality/inequality residuals, and objective. Keep raw solver output and checker output together. + +An “infeasible” conclusion requires a certificate or a solver status that actually proves infeasibility. A timeout, memory stop, numerical failure, or unknown status means unresolved. Relax constraints only as a named scenario and rerun the full audit; never silently relax them in post-processing. diff --git a/constrained-optimization/references/multiobjective-and-robustness.md b/constrained-optimization/references/multiobjective-and-robustness.md new file mode 100644 index 0000000..c538db1 --- /dev/null +++ b/constrained-optimization/references/multiobjective-and-robustness.md @@ -0,0 +1,7 @@ +# Pareto and robustness decisions + +When objectives conflict, first identify dominated candidates. A candidate is dominated if another is at least as good on every objective and strictly better on one, under the same feasibility rules. Present the remaining nondominated set with units and constraint residuals. Choose a point only after the decision maker states weights, lexicographic priorities, epsilon limits, or a policy preference. A weighted sum is a decision choice, not a neutral truth. + +For noisy or stochastic objectives, define the randomization source and evaluation protocol. Use equal evaluation budgets, paired seeds where appropriate, and report mean/median, spread, worst observed feasible result, and failure/violation rate. Separate uncertainty in the objective measurement from uncertainty in the search procedure. Investigate a candidate that wins only because it has more attempts or a lucky seed. + +Stress the selected solution against plausible parameter, demand, and constraint-bound changes. Record which constraints become active, which objective moves first, and whether a nearby feasible alternative is safer. Robustness evidence can justify a less optimal nominal point, but the preference must be explicit and the solution must remain feasible under the stated scenario. diff --git a/constrained-optimization/references/source-index.md b/constrained-optimization/references/source-index.md new file mode 100644 index 0000000..081d287 --- /dev/null +++ b/constrained-optimization/references/source-index.md @@ -0,0 +1,11 @@ +# Primary sources and applicability + +Checked 2026-09-14. These links support interpretation of solver evidence; this methodology does not install or operate these tools. Record the installed solver version, selected method, options, and matching documentation in each solution audit. + +| Source | Documentation scope observed | Use and limit | +|---|---|---| +| [SciPy OptimizeResult](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.OptimizeResult.html) | SciPy 1.18.0 reference | Explains success, status, termination messages, and optional result fields. Available fields and status meanings depend on the solver; successful termination alone is not a universal global-optimality certificate. | +| [SciPy linprog](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.linprog.html) | SciPy 1.18.0 reference | Defines linear objectives, constraints, bounds, residuals, and method-specific results. Recompute constraints from the original formulation and declared tolerance. Do not transfer linear-programming guarantees to nonlinear or heuristic methods. | +| [OR-Tools CP-SAT](https://developers.google.com/optimization/cp/cp_solver) | Unversioned official guide, checked on the date above | Describes integer constraint models and distinct optimal, feasible, infeasible, invalid-model, and unknown outcomes. Preserve the returned status; a search limit does not establish infeasibility. Integer scaling and finite domains must preserve the intended formulation. | + +Re-check the exact release and algorithm before relying on a field, tolerance, gap, or certificate. These sources illustrate evidence interpretation; they do not make one solver suitable for every formulation or validate an application model. diff --git a/constrained-optimization/templates/formulation-record.md b/constrained-optimization/templates/formulation-record.md new file mode 100644 index 0000000..f617b09 --- /dev/null +++ b/constrained-optimization/templates/formulation-record.md @@ -0,0 +1,38 @@ +# Optimization formulation record + +## Decision + +- Problem and decision owner: +- Data/configuration revision: +- Decision horizon and compute budget: +- Known feasible incumbent: + +## Variables + +| Variable | Domain | Bounds/allowed values | Unit | Controllable? | +|---|---|---|---|---| +| | | | | | + +## Objectives + +| Objective | Direction | Unit | Aggregation/reference | Priority or weight | +|---|---|---|---|---| +| | | | | | + +## Constraints + +| Constraint | Hard/soft | Expression and tolerance | Unit | Violation measure/penalty | +|---|---|---|---|---| +| | | | | | + +- Feasibility predicate/checker: +- Relaxed scenarios (if any): + +## Method and decision rule + +- Exact/certifying baseline: +- Heuristic baseline: +- Initialization and seed/repeat plan: +- Stopping rule and equal budget: +- Pareto/weight/lexicographic decision rule: +- Selection threshold and rollback/re-optimization trigger: diff --git a/constrained-optimization/templates/solution-audit.md b/constrained-optimization/templates/solution-audit.md new file mode 100644 index 0000000..fc59449 --- /dev/null +++ b/constrained-optimization/templates/solution-audit.md @@ -0,0 +1,33 @@ +# Optimization solution audit + +- Formulation record and revision: +- Candidate/source method: +- Solver status and termination message: +- Runtime/evaluation budget: +- Seed/repeat (if stochastic): + +## Independent recomputation + +| Check | Result | Tolerance | Evidence | +|---|---:|---:|---| +| Objective(s), with units | | | | +| Variable domains/bounds | | | | +| Hard-constraint residuals | | | | +| Soft-constraint violations | | | | +| Independent feasibility predicate | | | | + +## Quality evidence + +- Best feasible objective: +- Infeasible candidate objective (if retained for diagnosis): +- Bound and gap definition/value: +- Repeat distribution and failure rate: +- Pareto alternatives or selected weights: +- Sensitivity/robustness result: + +## Decision + +- Verdict: accept / reject / unresolved / infeasible-proven +- Rationale and tradeoff: +- Missing evidence or limitations: +- Owner, approval, and next trigger: diff --git a/llms.txt b/llms.txt index 4c4bdfc..13dedaf 100644 --- a/llms.txt +++ b/llms.txt @@ -28,6 +28,7 @@ - [color-management](color-management/SKILL.md): Manage color workflows with ICC profiles, working spaces, gamut mapping, and color science. Use when inspecting ICC profiles, converting between color spaces, checking gamut clipping, validating well-behaved working spaces, or troubleshooting color workflow issues with ImageMagick, ArgyllCMS, Exiftool, or LittleCMS. Do not use this skill for unrelated requests; route to the nearest named specialist. - [conditional-customer-success](conditional-customer-success/SKILL.md): Guide recurring human-relationship practices — success plans, health evidence, renewal and expansion signals, QBRs, handoffs, escalation, and closed-loop Voice of Customer. Do not use this skill for products without accounts, renewals, QBRs, or a customer-success team, including some internal tools, pure transactional products without recurring relationships, and public services without account-based engagement. Load only when the product context includes a recurring human relationship; decline or route away otherwise. - [confluence-cli](confluence-cli/SKILL.md): Interact with Atlassian Confluence from the terminal: list spaces, browse pages, view page content, search with CQL, and create pages. Use when the user mentions Confluence, a space key (e.g. DEV), or asks about documentation, wiki pages, space content, or knowledge base articles. Do not use this skill for unrelated requests; route to the nearest named specialist. +- [constrained-optimization](constrained-optimization/SKILL.md): Define, compare, and audit constrained optimization decisions with explicit variables, units, hard and soft constraints, feasibility, Pareto tradeoffs, and honest solver evidence. Do not use for statistical modeling or ML fitting, which belong to data-scientist or ml-engineering, or for operating a named solver. - [crewai](crewai/SKILL.md): Build role-based multi-agent systems with CrewAI. Agents with Role/Goal/Backstory, task design, crew composition (sequential or hierarchical), tool integration, callbacks, and production deployment. Use when orchestrating multi-agent teams or comparing agent frameworks. Do not use this skill for unrelated requests; route to the nearest named specialist. - [crm](crm/SKILL.md): Operate HubSpot CRM from a terminal or agent: list and search contact records, view deal pipeline stages, and — with explicit confirmation — move deals between stages, backed by a bundled crm-cli script that is read-only by default and gates every stage change behind a --dry-run/--yes confirmation. Use when an agent needs to answer questions about contacts or deals, produce pipeline views, or apply a confirmed stage change. Do not use for building HubSpot apps or workflow automations (that is HubSpot app development), marketing/sequence automation, or other CRMs like Salesforce (that is their own tooling). - [crowdsec](crowdsec/SKILL.md): Deploy, configure, and operate CrowdSec Security Engine, cscli, remediation components, acquisition pipelines, and AppSec WAF. Use for Linux or Docker installation, detection-to-blocking design, incident review, and safe changes. Do not use for generic firewall, Kubernetes, or reverse-proxy design; route those to the named platform skill and use this skill for CrowdSec integration.