1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
---
name: bare-metal-alara
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 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, identify:
- 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
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.
## Create The Ledger
Before the first optimization edit, create one persistent ledger:
```text
/tmp/bare-metal-alara-<repo-or-dir>-<target-slug>.md
```
Use this shape:
```text
ledger_path:
target:
scope:
workload:
metric:
correctness_oracle:
benchmark_command:
constraints:
environment:
baseline:
profile_summary:
memory_sanity:
experiment_ledger:
verification:
final_measurement:
speedup:
residual_opportunities:
```
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.
## Memory Sanity
Wallclock is the primary score, but memory is often the hidden throttle. During baseline or profiling, ask whether peak RSS, allocation rate, retained heap, cache footprint, page faults, copy volume, or allocator churn could dominate the workload or silently regress during speed work.
Do not run a full memory profiler by rote. If the workload is tiny, bounded, streaming, or obviously not memory-sensitive, record that judgment in one line. If memory could plausibly matter, take the cheapest useful measurement first: peak RSS, allocation counts, heap profile, allocator trace, or language/runtime equivalent. Escalate only when the cheap signal suggests bloat, churn, leaks, pathological retention, or a speedup that buys time by exploding memory.
Treat runaway memory as an ALARA defect even when wallclock improves. A change that is faster only by allocating absurdly more memory does not automatically pay rent; keep it only if the workload and constraints justify the trade.
## Experiment Loop
For each optimization attempt, append a ledger row:
```text
id:
hypothesis:
evidence:
planned_change:
risk:
pre_measurement:
edit_summary:
correctness_result:
post_measurement:
decision: keep | revert | revise | superseded
next:
```
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, including memory sanity result when relevant
- kept optimization batches
- reverted or rejected experiments, if important
- residual opportunities judged unreasonable or out of scope
## Hard Failure Modes
- 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
|