cuopt-skill-evolution

What this skill does

# Skill Evolution

Skills improve through a single workflow: solve the user's problem, notice when a generalizable learning surfaced, score it if you can, then propose an update. The presence or absence of ground truth changes the *confidence* attached to a proposal, not the steps you take.

## Trigger conditions

You MUST evaluate whether to enter the skill evolution workflow when ANY of these events occur during a conversation:

1. **User correction** — The user corrects your output (e.g., "the answer should be X", "no, use Y instead of Z"). A correction means the skill that guided you was missing information.
2. **Retry after failure** — Your code/formulation failed (wrong result, solver error, runtime exception) and you had to change approach. The fix likely contains a generalizable pattern.
3. **Undocumented behavior** — You discovered an API behavior, default value, or constraint not mentioned in the relevant skill.
4. **Workaround** — You had to work around a limitation or gotcha not documented in any skill.
5. **Variable type or modeling error** — You chose the wrong variable type (e.g., CONTINUOUS vs INTEGER), constraint form, or objective structure, and the correction changed the result.
6. **Thrash before landing** — You arrived at the right answer, but only after visibly thrashing: writing dead code that you then deleted, rewriting the same construct multiple times, or exploring 2+ approaches before settling. The final code looks fine, but the path to it shows the skill failed to point you at the right pattern from the start. The fix is usually a worked example or a "prefer X over Y" note that would have saved the detour.

**When a trigger fires:** Finish solving the user's problem first, then evaluate whether the learning is generalizable (not user-specific) before entering the workflow below.

**Do NOT trigger for:** Trivial typos, user-specific data/paths, one-off configuration issues, or problems already covered by existing skills.

## Workflow

1. **Solve the user's problem first.** Read the relevant skills, produce a solution, ship the fix. Skill evolution never blocks the user's task.
2. **Notice if a trigger fired** (see Trigger conditions above). If nothing surfaced a generalizable learning, you are done.
3. **Try to score the learning — when ground truth exists.** A test exists, a known-correct answer is available, the solver returns a check-able status, etc. If the score fails, refine the candidate learning — tune the pattern, fix the example, add the missing detail — and re-score. Iterate until it scores or you conclude no version of it will; in the latter case, drop the proposal rather than ship an unscored claim. (See Scoring criteria below for what counts as ground truth.)
4. **If no ground truth is available to score against** — no test to run, no comparable answer to check against, no solver to invoke — skip step 3 and proceed with `scored: no`. This is normal during inference-style interactions where the learning is qualitative — the proposal is still useful, just lower-confidence.
5. **Distill, place, and propose** (see sections below). Apply only after the user approves.
6. **Treat recurrence as evidence.** When the same unscored insight surfaces in 2+ independent interactions, the recurrence is itself a signal. Promote the insight to a stronger proposal — note the prior occurrences in the trigger field rather than re-deriving from scratch.

The loop has no hard iteration cap. The right number of refinement passes is whatever lets you confidently say "this scored" or "this won't score, dropping it." Forcing a count adds ceremony without changing the outcome.

### Scoring criteria

Use whatever ground truth is available:

| Ground truth | How to score |
|---|---|
| Behavioral tests | `must_include` / `must_not_include` patterns pass |
| Code execution | `solution.py` runs without error, produces expected output |
| Solver status | cuOpt returns `Optimal` / `FeasibleFound` / `SUCCESS` |
| Constraint satisfaction | All constraints in the formulation are met |
| Known answer | Output matches the expected value within tolerance |

If no ground truth is available, the proposal proceeds with `scored: no` — see the Workflow.

### Distillation

When the score passes, distill the learning into a skill artifact. Two types:

**Markdown** (SKILL.md patches) — gotchas, patterns, examples, table rows:
- Identify which `skills/*/SKILL.md` would benefit
- Extract the general pattern from the specific fix
- Write the exact addition (new row, new subsection, new code example)

**Code** (assets/*.py) — reusable helper functions, reference solutions:
- Place in `skills/*/assets/` alongside existing assets
- Must be runnable by `ci/test_skills_assets.sh`
- Include a docstring explaining what the code does and why it was extracted

### Choosing Markdown vs code asset

Default to Markdown. Promote to a code asset only when the learning is a chunk of logic that downstream users would otherwise rewrite — typically when:

- The same helper has been independently written in 2+ interactions (the recurrence is the signal)
- The fix is more than ~15 lines of code, where embedding it as an example would dwarf the surrounding prose
- It encodes a non-trivial algorithm (e.g. a constraint-builder, a formulation transform) that is easier to *call* than to read and re-implement

A one-liner gotcha or a 3-line pattern belongs in Markdown. A reusable function that several future problems will want to import belongs in `assets/`.

### Writing style

How a proposal is *written* matters as much as what it says. Skills are read on every future invocation, so prose has to earn its place.

- **Imperative form.** "Use `LinearExpression(...)` for large objectives" beats "It is recommended that one consider using `LinearExpression(...)` when the objective is large."
- **Explain the why.** A rule with no rationale rots — readers can't tell if it still applies. Pair every constraint with the reason it exists ("because chained `+` hits Python's recursion limit at ~1000 terms"). Today's models reason well from causes; they follow blind rules badly.
- **Don't overfit to the triggering case.** The point of a skill is to help across a million future prompts, not to memorize the one that surfaced the lesson. Strip user-specific names, sizes, paths, and objective values. State the pattern at the level of "any LP with a large objective," not "the 5000-variable factory problem from the user's data."
- **Avoid MUST-walls.** Stacking ALL-CAPS imperatives ("MUST", "ALWAYS", "NEVER") trains the reader to skim over them. Reserve them for genuine safety rules. For ergonomic guidance, prefer plain prose with the reasoning inline — the reader can then apply judgment to edge cases.
- **Match the surrounding style.** A new table row in a table; a new subsection where subsections already exist; a new bullet in a bullet list. Don't introduce a heading style or formatting convention that the target skill doesn't already use.

If a draft proposal feels heavy-handed or rigid, rewrite it as if explaining the lesson to a colleague who has never seen the bug. That tone usually lands closer to what works.

### Placement rule — target highest-impact skill

Always place the learning in the **single skill where it has the widest effect**. Do NOT duplicate the same content across multiple skills.

Choose the target using this priority:
1. **Common / concept skill** (e.g. `cuopt-numerical-optimization-formulation`, `cuopt-routing-formulation`, `cuopt-user-rules`) — if the learning applies regardless of language or interface, put it here. All downstream API skills already read the common skill.
2. **API skill** (e.g. `cuopt-numerical-optimization-api-python`, `cuopt-routing-api-python`) — if the learning is specific to one API or language.
3. **New skill** — only if the learning doesn't fit any existing skill.

If a gotcha affects both Python and C users but is about the solver behavior (not the A