optimize

Name: optimize
Author: Borda

23stars3forks

How to install optimize?

borda/ai-rig/optimize

$npx -y skills add Borda/AI-Rig --skill optimize

Installs into the current project.

Summary

Minimal codex-native optimization loop. Use for metric-driven improvements with guardrails and measurable gates.

Files · 1

View on GitHub

SKILL.md

1	# Optimize
2
3	Metric-driven optimization with explicit guards, rollback criteria, experiment log.
4
5	## Input Schema
6
7	```json
8	{
9	"goal": "required measurable improvement objective",
10	"mode": "single\|campaign",
11	"metric_cmd": "required command that emits or validates the target metric",
12	"metric_direction": "higher\|lower",
13	"guard_cmd": "required command that must continue to pass",
14	"max_iterations": "optional integer, default 1",
15	"min_delta": "optional practical significance threshold",
16	"scope_files": [
17	"paths the optimization may edit"
18	],
19	"done_when": "metric improves without guard regression"
20	}
21	```
22
23	## Workflow
24
25	### 01: Create run directory
26
27	Run `python PLUGIN_ROOT/shared/create_run.py --skill optimize` once. Retain its single printed path as
28	`<run-directory>` and substitute that literal path into every later artifact path and helper argument. Never store or
29	reuse the path through a shell variable; shell variables do not persist across tool calls.
30
31	### 02: Validate metric and guard commands
32
33	Require:
34
35	- Repeatable `metric_cmd` producing comparable value or pass/fail.
36	- Known `metric_direction`.
37	- `guard_cmd` fails on unacceptable regressions.
38	- Bounded `scope_files`.
39	- Explicit, bounded `max_iterations` for `campaign`.
40	- Protect files/scripts used by `metric_cmd`/`guard_cmd` unless user explicitly scopes them and accepts measurement-integrity risk.
41
42	Dry-run both before edit:
43
44	Execute the configured `metric_cmd` and `guard_cmd` separately with the host-native command runner. Write complete
45	combined output to `<run-directory>/metric-baseline.txt` and `<run-directory>/guard-baseline.txt`; retain both exit
46	codes and stop before editing if either command cannot run.
47
48	### 03: Record baseline and hypothesis
49
50	Write `<run-directory>/hypothesis.md`:
51
52	- metric to improve
53	- expected mechanism
54	- files allowed to change
55	- guard risk
56	- rollback condition
57
58	For `campaign`, noisy metrics, GPU/ML performance, or correctness-sensitive code, apply `../../shared/specialist-orchestration.md`. Write `<run-directory>/specialist-optimization-plan.md` with narrow context packs for:
59
60	- `squeezer`: profiling mechanism, bottleneck hypothesis, measurement plan.
61	- `qa-specialist`: guard coverage and regression risk.
62	- `data-steward`: data pipeline or reproducibility impact.
63	- `scientist`: metric validity, ablation design, statistical noise.
64	- `challenger`: overfitting to the metric or weakening guard checks.
65
66	No fan-out for one small measured change with stable metric/guard. Never let specialist change metric/guard scripts unless explicitly in `scope_files` and measurement-integrity risk recorded.
67
68	Initialize machine-readable iteration log:
69
70	Create an empty `<run-directory>/experiments.jsonl` with the filesystem tool before the first iteration.
71
72	### 04: Apply one minimal optimization change per iteration
73
74	One independent hypothesis per iteration. Do not optimize unmeasured paths. Before each, write `<run-directory>/iteration-<n>-before.patch` with scoped-file diff. If iteration fails and only its patch is present, revert with `git apply -R` against iteration diff; otherwise fail run when clean reversal cannot be proven. Never use `git reset --hard`.
75
76	### 05: Re-measure
77
78	Re-run the same retained `metric_cmd` and `guard_cmd` separately with the host-native command runner. Write complete
79	combined output to `<run-directory>/metric-after.txt` and `<run-directory>/guard-after.txt`; retain both exit codes.
80
81	### 06: Compare baseline and after results in `<run-directory>/comparison.md`
82
83	Required fields:
84
85	- baseline value
86	- after value
87	- delta
88	- guard status
89	- confidence
90	- noise caveats
91
92	Append one JSON object/iteration to `<run-directory>/experiments.jsonl`:
93
94	```json
95	{
96	"iteration": 1,
97	"hypothesis": "one-line mechanism",
98	"metric_before": 0.0,
99	"metric_after": 0.0,
100	"delta": 0.0,
101	"guard": "pass\|fail",
102	"decision": "kept\|reverted\|inconclusive\|failed",
103	"rollback_evidence": "path or reason"
104	}
105	```
106
107	### 07: Decide keep/revert
108
109	- Keep only with intended metric movement and passing guards.
110	- With `min_delta`, keep only if delta meets/exceeds practical-significance threshold.
111	- Revert or fail on guard regression.
112	- For noisy measurement, repeat or mark inconclusive.
113	- In `campaign`, stop at first kept result unless user asked continued exploration; otherwise continue only while `max_iterations` remains and each rejected iteration has rollback evidence.
114
115	### 08: Run shared quality gates
116
117	Inspect `python PLUGIN_ROOT/shared/run_gates.py --help`. Tests runs configured test or guard command; give real commands or explicit reasons for other gates.
118
119	### 09: Write and validate the mandatory result artifact
120
121	Follow `../../shared/helper-cli-contract.md` and authoritative help. Write `OPTIMIZE_METADATA`, validate as `optimize`, promote only validated candidate.
122
123	## Fail-Fast Rules
124
125	1. Missin

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

optimize

23stars3forks

View on GitHub

How to install optimize?

borda/ai-rig/optimize

$npx -y skills add Borda/AI-Rig --skill optimize

Installs into the current project.

Summary

Minimal codex-native optimization loop. Use for metric-driven improvements with guardrails and measurable gates.

Files · 1

View on GitHub

SKILL.md

1	# Optimize
2
3	Metric-driven optimization with explicit guards, rollback criteria, experiment log.
4
5	## Input Schema
6
7	```json
8	{
9	"goal": "required measurable improvement objective",
10	"mode": "single\|campaign",
11	"metric_cmd": "required command that emits or validates the target metric",
12	"metric_direction": "higher\|lower",
13	"guard_cmd": "required command that must continue to pass",
14	"max_iterations": "optional integer, default 1",
15	"min_delta": "optional practical significance threshold",
16	"scope_files": [
17	"paths the optimization may edit"
18	],
19	"done_when": "metric improves without guard regression"
20	}
21	```
22
23	## Workflow
24
25	### 01: Create run directory
26
27	Run `python PLUGIN_ROOT/shared/create_run.py --skill optimize` once. Retain its single printed path as
28	`<run-directory>` and substitute that literal path into every later artifact path and helper argument. Never store or
29	reuse the path through a shell variable; shell variables do not persist across tool calls.
30
31	### 02: Validate metric and guard commands
32
33	Require:
34
35	- Repeatable `metric_cmd` producing comparable value or pass/fail.
36	- Known `metric_direction`.
37	- `guard_cmd` fails on unacceptable regressions.
38	- Bounded `scope_files`.
39	- Explicit, bounded `max_iterations` for `campaign`.
40	- Protect files/scripts used by `metric_cmd`/`guard_cmd` unless user explicitly scopes them and accepts measurement-integrity risk.
41
42	Dry-run both before edit:
43
44	Execute the configured `metric_cmd` and `guard_cmd` separately with the host-native command runner. Write complete
45	combined output to `<run-directory>/metric-baseline.txt` and `<run-directory>/guard-baseline.txt`; retain both exit
46	codes and stop before editing if either command cannot run.
47
48	### 03: Record baseline and hypothesis
49
50	Write `<run-directory>/hypothesis.md`:
51
52	- metric to improve
53	- expected mechanism
54	- files allowed to change
55	- guard risk
56	- rollback condition
57
58	For `campaign`, noisy metrics, GPU/ML performance, or correctness-sensitive code, apply `../../shared/specialist-orchestration.md`. Write `<run-directory>/specialist-optimization-plan.md` with narrow context packs for:
59
60	- `squeezer`: profiling mechanism, bottleneck hypothesis, measurement plan.
61	- `qa-specialist`: guard coverage and regression risk.
62	- `data-steward`: data pipeline or reproducibility impact.
63	- `scientist`: metric validity, ablation design, statistical noise.
64	- `challenger`: overfitting to the metric or weakening guard checks.
65
66	No fan-out for one small measured change with stable metric/guard. Never let specialist change metric/guard scripts unless explicitly in `scope_files` and measurement-integrity risk recorded.
67
68	Initialize machine-readable iteration log:
69
70	Create an empty `<run-directory>/experiments.jsonl` with the filesystem tool before the first iteration.
71
72	### 04: Apply one minimal optimization change per iteration
73
74	One independent hypothesis per iteration. Do not optimize unmeasured paths. Before each, write `<run-directory>/iteration-<n>-before.patch` with scoped-file diff. If iteration fails and only its patch is present, revert with `git apply -R` against iteration diff; otherwise fail run when clean reversal cannot be proven. Never use `git reset --hard`.
75
76	### 05: Re-measure
77
78	Re-run the same retained `metric_cmd` and `guard_cmd` separately with the host-native command runner. Write complete
79	combined output to `<run-directory>/metric-after.txt` and `<run-directory>/guard-after.txt`; retain both exit codes.
80
81	### 06: Compare baseline and after results in `<run-directory>/comparison.md`
82
83	Required fields:
84
85	- baseline value
86	- after value
87	- delta
88	- guard status
89	- confidence
90	- noise caveats
91
92	Append one JSON object/iteration to `<run-directory>/experiments.jsonl`:
93
94	```json
95	{
96	"iteration": 1,
97	"hypothesis": "one-line mechanism",
98	"metric_before": 0.0,
99	"metric_after": 0.0,
100	"delta": 0.0,
101	"guard": "pass\|fail",
102	"decision": "kept\|reverted\|inconclusive\|failed",
103	"rollback_evidence": "path or reason"
104	}
105	```
106
107	### 07: Decide keep/revert
108
109	- Keep only with intended metric movement and passing guards.
110	- With `min_delta`, keep only if delta meets/exceeds practical-significance threshold.
111	- Revert or fail on guard regression.
112	- For noisy measurement, repeat or mark inconclusive.
113	- In `campaign`, stop at first kept result unless user asked continued exploration; otherwise continue only while `max_iterations` remains and each rejected iteration has rollback evidence.
114
115	### 08: Run shared quality gates
116
117	Inspect `python PLUGIN_ROOT/shared/run_gates.py --help`. Tests runs configured test or guard command; give real commands or explicit reasons for other gates.
118
119	### 09: Write and validate the mandatory result artifact
120
121	Follow `../../shared/helper-cli-contract.md` and authoritative help. Write `OPTIMIZE_METADATA`, validate as `optimize`, promote only validated candidate.
122
123	## Fail-Fast Rules
124
125	1. Missin

People who liked this also viewed

6 picks

Type