| name | performance-fix |
| description | This skill should be used when the user asks to "fix performance issues", "optimise the bottlenecks", "implement the performance fixes", "apply the performance report", "speed this up based on the report", or wants to act on a performance report produced by /performance-analyse. Reads a performance report and implements targeted fixes. |
| version | 0.1.0 |
Performance Engineer
Fix exactly one performance bottleneck per invocation. If the target issue is unclear, interview the user before writing any code.
Workflow
- Identify the target — Determine which single bottleneck to fix:
- If the user named a specific hotspot or issue number from the report, use that
- If the user's request is vague ("fix performance", "speed this up"), load
perf-report.md and ask the user which hotspot to tackle — list the hotspots with their severity and let them choose
- If
perf-report.md does not exist or does not contain the issue the user describes, interview the user: ask what is slow, how they observe it, what workload triggers it, and what "fast enough" means — then suggest running /performance-analyse first
- Never guess which issue to fix. Always confirm the target with the user before writing code.
- Fix one bottleneck:
a. Understand the root cause from the report (or from the user interview)
b. Implement a minimal, targeted fix
c. Build in release mode
d. Re-measure using the same benchmark from the report
e. Record before/after numbers
f. If improvement is <2% or not statistically significant, reconsider the approach
- Update report — Append the fix result to
perf-report.md with before/after measurements
- Done — Present the result. Do not proceed to the next bottleneck unless the user explicitly asks
Fix Strategies by Bottleneck Type
Allocation-bound
| Symptom | Fix |
|---|
Repeated Vec growth | Vec::with_capacity() or reserve() |
format!/to_string in hot path | Pre-allocate buffer, use write! |
| Many small short-lived allocations | Arena allocator (bumpalo), SmallVec |
| Excessive cloning | Borrow instead, Cow<'_, T>, Rc/Arc |
CPU-bound
| Symptom | Fix |
|---|
| O(n^2) algorithm | Replace with O(n log n) or O(n) |
| Missed auto-vectorization | Restructure loop, use iterators |
| Redundant computation | Cache/memoize results, LazyLock for statics |
| Dynamic dispatch in hot loop | Enum dispatch or monomorphize with generics |
Memory-bound (cache misses)
| Symptom | Fix |
|---|
| AoS with partial field access | Restructure to SoA |
| Pointer chasing (linked list, tree) | Flatten to Vec, use indices |
| Large structs in hot iteration | Split hot/cold fields |
| Random access patterns | Sort data for sequential access |
Branch-bound
| Symptom | Fix |
|---|
| Unpredictable branches in tight loop | Branchless arithmetic |
| Trait object dispatch | Enum dispatch |
| Frequent bounds checks | Use iterators, chunks_exact |
Re-measurement Protocol
After each fix:
- Before the fix — measure the current state with the same workload/benchmark from the report
- Apply the fix and build with
cargo build --release
- After the fix — re-run the exact same workload/benchmark
- Compare the before/after numbers from steps 1 and 3 to isolate this fix's impact
- Also record cumulative improvement vs the original report baseline
- Record: function/area, what changed, pre-fix time, post-fix time, speedup factor, cumulative speedup vs original
- If criterion is available, check that
p < 0.05 (statistically significant)
Results Format
Append to the report:
## Fix Results
### Fix: <description>
- **Bottleneck:** Hotspot N from report
- **Change:** <what was modified>
- **Before:** X.XXms (median)
- **After:** X.XXms (median)
- **Speedup:** X.Xx
- **Commit:** <hash>
Principles
- One fix per invocation — fix exactly one bottleneck, then stop. The user invokes again for the next one.
- Clarify before coding — if the target is ambiguous or missing from the report, ask. Never assume.
- Minimal changes — change only what the bottleneck requires; do not refactor surrounding code
- Data over intuition — if the measurement shows no improvement, revert
- No premature optimisation — only fix what the report identifies; do not speculatively optimise other areas
Additional Resources
references/methodologies.md — Statistical benchmarking, allocation reduction patterns, cache optimisation strategies, and detailed code examples
