performance-fix · diff
v0.1.0 to v0.1.0
13 added, 18 removed. Audit A to A.
---
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
- Implement targeted fixes for performance bottlenecks identified in a report. This role modifies code: **one fix at a time, re-measure after each.**
+ Fix exactly **one** performance bottleneck per invocation. If the target issue is unclear, interview the user before writing any code.
## Workflow
- 1. **Read report** — Load `perf-report.md` (or a user-specified report file) and parse the recommendations
- 2. **Prioritise** — Work through bottlenecks in the order listed (highest impact first)
- 3. **For each bottleneck:**
- a. Understand the root cause from the report
+ 1. **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.
+ 2. **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
- 4. **Update report** — Append results to the report with before/after measurements
- 5. **Summarise** — Present total improvement vs original baseline
+ 3. **Update report** — Append the fix result to `perf-report.md` with before/after measurements
+ 4. **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:
1. Build with `cargo build --release`
2. Run the exact same workload/benchmark from the report
3. Compare against the report's baseline (not the previous fix)
4. Record: function/area, what changed, before time, after time, speedup factor
5. If criterion is available, check that `p < 0.05` (statistically significant)
## Results Format
Append to the report:
```markdown
## Fix Results
- ### Fix 1: <description>
+ ### Fix: <description>
- **Bottleneck:** Hotspot N from report
- **Change:** <what was modified>
- **Before:** X.XXms (median)
- **After:** X.XXms (median)
- **Speedup:** X.Xx
- **Commit:** <hash>
-
- ### Fix 2: ...
-
- ## Overall
-
- | Metric | Before | After | Improvement |
- |--------|--------|-------|-------------|
- | Wall-clock (median) | X.XXs | X.XXs | X.Xx faster |
```
## Principles
- - **One fix at a time** — never bundle multiple optimisations in one step; each must be independently measured
+ - **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
- - **Stop when done** — if the target metric is met or no dominant hotspot remains, stop
- **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