diff options
| -rw-r--r-- | bare-metal-alara/SKILL.md | 134 | ||||
| -rw-r--r-- | bare-metal-alara/agents/openai.yaml | 4 |
2 files changed, 105 insertions, 33 deletions
diff --git a/bare-metal-alara/SKILL.md b/bare-metal-alara/SKILL.md index 52c3f44..3668d6e 100644 --- a/bare-metal-alara/SKILL.md +++ b/bare-metal-alara/SKILL.md @@ -1,56 +1,128 @@ --- name: bare-metal-alara -description: "Use when the user wants a standard Bare Metal ALARA performance goal: lock the workload and correctness oracle, write a terse .goals/ acceptance contract, install it as a Codex /goal when possible, then profile and optimize runtime as low as reasonably achievable without semantic drift or gratuitous uglification." +description: "Use when the user wants a standalone Bare Metal ALARA performance pass: lock the workload and correctness oracle, create a /tmp optimization ledger, profile, optimize, verify behavior, and drive wallclock runtime as low as reasonably achievable without semantic drift or gratuitous uglification." --- # Bare Metal ALARA -Bring the specified implementation's runtime As Low As Reasonably Achievable for the agreed workload while preserving existing business behavior and public contracts. Use measurement and profiling to discover the true limiting structure, then reshape code, data, and algorithms freely when the result is materially faster and not gratuitously contorted. +Bring the specified implementation's wallclock runtime As Low As Reasonably Achievable for the agreed workload while preserving existing business behavior and public contracts. Use measurement and profiling to discover the true limiting structure, then reshape code, data, and algorithms freely when the result is materially faster and not gratuitously contorted. -Lock the target before optimizing. Inspect enough of the repo to identify the implementation surface, but if any uncertainty remains about the representative workload, benchmark command, input distribution, correctness oracle, public contract, scope boundary, performance metric, or forbidden tradeoff, explicitly ask the user to clarify. Do not proceed under a guessed workload. +## Lock The Target -Create a repo-root `.goals/<slug>.md` contract before the long optimization pass. Create `.goals/` if needed. Ensure `.goals/` is gitignored; if it is not ignored, add `.goals/` to the repo-root `.gitignore`. Keep the document short and acceptance-first. Do not prescribe tactics unless the user explicitly freezes them. Prefer named references over copied plans or benchmark notes. +Before optimizing, identify: -Use this goal shape: +- target implementation surface +- representative workload +- benchmark command or measurement method +- primary performance metric, defaulting to wallclock runtime +- correctness oracle +- scope boundary +- forbidden tradeoffs, if any -```markdown -# Goal: Bare Metal ALARA For <target> +Inspect enough of the repo to find likely commands and surfaces. If any material uncertainty remains about the workload, input distribution, correctness oracle, public contract, benchmark command, or forbidden tradeoff, explicitly ask the user to clarify. Do not optimize a guessed workload. -## Objective -Reduce runtime for <workload> as low as reasonably achievable while preserving the existing business behavior and public contracts of <target>. +## Create The Ledger -## References -- `<benchmark or command>`: authoritative performance measurement -- `<tests or oracle>`: authoritative behavior preservation check -- `<paths>`: implementation surface in scope +Before the first optimization edit, create one persistent ledger: -## Acceptance Criteria -- Behavior remains preserved according to <oracle>. -- The agreed workload is benchmarked before and after optimization. -- Runtime improves materially on the agreed workload, or the final report shows why remaining plausible gains are unreasonable. -- No semantic changes, gratuitous obscurity, or unjustified high-risk low-level techniques are introduced. - -## Verification -- `<behavior command>` -- `<benchmark command>` -- Inspect changed implementation for disproportionate complexity or risk. +```text +/tmp/bare-metal-alara-<repo-or-dir>-<target-slug>.md ``` -Install the goal directly if goal tools are available and no goal already exists: call `get_goal`, then `create_goal` with this objective: +Use this shape: ```text -Read .goals/<slug>.md and complete every acceptance criterion in it. Mark the goal complete only after the verification evidence required by that file is satisfied. +ledger_path: +target: +scope: +workload: +metric: +correctness_oracle: +benchmark_command: +constraints: + +environment: +baseline: +profile_summary: + +experiment_ledger: + +verification: +final_measurement: +speedup: +residual_opportunities: ``` -If goal tools are unavailable, or if a goal already exists and cannot be safely replaced through tools, output the exact copyable command sequence: +The ledger is the durable campaign state. Chat is summary only. If interrupted or resumed, reopen the same ledger before continuing. + +## Baseline + +Run the correctness oracle first if cheap. Then establish a baseline for the agreed workload. Capture the exact command, inputs, environment facts that matter, and enough repeated measurements to distinguish a real gain from noise. + +If the benchmark is unstable, improve the measurement harness before optimizing. Do not launder noise into progress. + +## Profile + +Use the standard profiler, tracer, benchmark harness, flamegraph, allocation tool, query planner, runtime instrumentation, or language-specific equivalent appropriate to the target. Do not rewrite from vibes when profiling is practical. + +The point of profiling is not ritual. The point is to find the current limiting structure: algorithm, representation, allocation, layout, dispatch, I/O, synchronization, cache behavior, parsing, serialization, query shape, or benchmark harness overhead. + +## Experiment Loop + +For each optimization attempt, append a ledger row: ```text -/goal clear -/goal Read .goals/<slug>.md and complete every acceptance criterion in it. Mark the goal complete only after the verification evidence required by that file is satisfied. +id: +hypothesis: +evidence: +planned_change: +risk: +pre_measurement: +edit_summary: +correctness_result: +post_measurement: +decision: keep | revert | revise | superseded +next: ``` -If the user asked only to prepare the goal, stop there. Otherwise execute the ALARA pass immediately: establish the baseline, profile, change, verify behavior, remeasure, and repeat. Continue while evidence or strong mechanical reasoning suggests meaningful speed remains available at reasonable complexity and risk. Stop only when further gains require semantic change, ungrounded workload assumptions, unacceptable fragility, or uglification disproportionate to the win. +Prefer one hypothesis per experiment unless several changes are mechanically inseparable. Keep changes that materially improve the agreed metric without semantic drift or disproportionate complexity. Revert or revise changes that do not pay rent. + +Continue while evidence or strong mechanical reasoning suggests meaningful runtime remains available at reasonable complexity and risk. Stop when remaining plausible gains require semantic change, ungrounded workload assumptions, unacceptable fragility, unsafe or unjustified low-level tricks, platform contortions, or noise-scale wins. + +## Reasonable Means Ruthless, Not Reckless + +Low-level code is allowed. Algorithmic change is allowed. Data representation change is allowed. API reshaping inside the scoped implementation is allowed unless the user froze compatibility. + +Gratuitous cleverness is not allowed. Benchmark gaming is not allowed. Semantic drift is not allowed. Hidden global state, precision loss, lossy approximation, concurrency hazards, cache invalidation traps, and platform-specific contortions require explicit justification and usually explicit user permission. + +Unsafe code is not forbidden in principle, but it is never a casual move. Exhaust ordinary representation, algorithmic, allocation, traversal, and runtime-configuration wins first unless the project is already an unsafe or low-level domain. + +## Verification + +After each kept batch, run the correctness oracle and remeasure. After the final batch, run the narrowest meaningful full verification for the touched surface, then widen if the optimization crosses module, package, crate, service, or runtime boundaries. + +Behavior preservation beats speed. Wallclock performance on the agreed workload is the primary score. Secondary metrics explain the result; they do not replace it. + +## Final Response + +Always include: + +- `/tmp` ledger path +- target and workload +- baseline measurement +- final measurement and speedup +- benchmark and correctness commands used +- main profiling evidence +- kept optimization batches +- reverted or rejected experiments, if important +- residual opportunities judged unreasonable or out of scope -Low-level code is allowed. Gratuitous cleverness is not. Unsafe code, precision loss, lossy approximation, hidden global state, concurrency hazards, cache invalidation traps, and platform-specific contortions require explicit justification and usually explicit user permission. +## Hard Failure Modes -Final reporting must include the baseline, final measurement, commands used, the main structural changes, and any remaining plausible optimizations judged unreasonable. +- do not optimize a guessed workload +- do not skip the `/tmp` ledger +- do not report speedups without baseline and final measurements +- do not treat passing tests as proof of performance +- do not treat faster benchmarks as permission for semantic drift +- do not hide unfavorable experiments +- do not preserve compatibility by default when compatibility is the bottleneck diff --git a/bare-metal-alara/agents/openai.yaml b/bare-metal-alara/agents/openai.yaml index 3953c9e..8632ae3 100644 --- a/bare-metal-alara/agents/openai.yaml +++ b/bare-metal-alara/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Bare Metal ALARA" - short_description: "Drive runtime as low as reasonably achievable" - default_prompt: "Use $bare-metal-alara to lock the workload, write a .goals/ performance contract, install it as a Codex /goal, and execute the optimization pass." + short_description: "Standalone wallclock optimization campaign" + default_prompt: "Use $bare-metal-alara to lock the workload, create a /tmp performance ledger, profile, optimize, verify behavior, and drive runtime as low as reasonably achievable." |