docs: link performance issues to benchmark harnesses

Co-authored-by: codegirl007 <s.raide@gmail.com>

.github/issues/add-deterministic-sprite-performance-benchmark.md

@@ -97,25 +97,46 @@ and report backend details.
 
 Add a non-interactive benchmark target with two explicitly separate workloads.
 
-Add dedicated Makefile targets that always build optimized benchmark code:
+The committed harnesses are:
 
 ```make
-PERF_ITERATIONS ?= 2000000
-PERF_FRAMES ?= 1000
+PERF_ODIN_FLAGS ?= -debug -o:speed
 
 perf-draw:
-	odin run examples/draw_bench \
+	odin run benchmarks/draw_sprite \
 		-collection:pkg=. \
-		-debug -o:speed \
-		-define:PERF_ITERATIONS=$(PERF_ITERATIONS)
+		$(PERF_ODIN_FLAGS) \
+		-define:PERF_ITERATIONS=$(PERF_DRAW_ITERATIONS)
 
 perf-frame:
-	odin run examples/frame_bench \
+	odin run benchmarks/sprite_frame \
 		-collection:pkg=. \
-		-debug -o:speed \
-		-define:PERF_FRAMES=$(PERF_FRAMES)
+		$(PERF_ODIN_FLAGS) \
+		-define:PERF_FRAMES=$(PERF_FRAME_FRAMES) \
+		-define:PERF_SCENARIO=$(PERF_FRAME_SCENARIO)
 ```
 
+Run the standard workloads with:
+
+```bash
+# CPU-only draw preparation.
+make perf-draw
+
+# Complete frame: 128 visible sprites sharing one texture.
+make perf-frame PERF_FRAME_SCENARIO=0
+
+# Complete frame: every second sprite is fully offscreen.
+make perf-frame PERF_FRAME_SCENARIO=1
+
+# Complete frame: 128 sprites alternate between two texture objects.
+make perf-frame PERF_FRAME_SCENARIO=2
+```
+
+Every invocation prints the Git commit, Odin version, compiler flags, workload
+configuration, every trial, and the median. `perf-frame` waits for GPU idle
+after warm-up and after each measured frame batch so outstanding work is
+included.
+
 ### CPU queue benchmark
 
 - Construct `App`, `Character_Data`, and `Sprite` with real baked metadata.

.github/issues/add-order-safe-texture-batching.md

@@ -28,6 +28,21 @@ A temporary paired benchmark used:
 Sorting and grouping improved median frame time by approximately **1.9%**.
 Hardware drivers with higher draw-call overhead may show a different result.
 
+## Reproduction harness
+
+Run the committed alternating-texture workload on the baseline and candidate
+commits:
+
+```bash
+make perf-frame \
+	PERF_FRAME_SCENARIO=2 \
+	PERF_ODIN_FLAGS="-debug -o:speed"
+```
+
+Keep all `PERF_FRAME_*` values unchanged. The baseline should produce one
+texture run per sprite; the candidate should reduce runs only inside explicit
+reorder-safe groups. Compare `median_ms_per_frame` and verify rendered output.
+
 ## Suggested fix
 
 Add an explicit batch group to queued sprites. Group `0` keeps strict submission

.github/issues/enable-sdl-gpu-buffer-cycling.md

@@ -32,6 +32,20 @@ A temporary paired benchmark used:
 Cycling improved median frame time by approximately **0.7%**. This is a small
 performance change, but it also follows SDL's documented resource-reuse model.
 
+## Reproduction harness
+
+Run the committed full-frame harness on the baseline commit and candidate
+commit:
+
+```bash
+make perf-frame \
+	PERF_FRAME_SCENARIO=0 \
+	PERF_ODIN_FLAGS="-debug -o:speed"
+```
+
+Keep all `PERF_FRAME_*` values unchanged. Compare `median_ms_per_frame`; the
+harness waits for GPU idle before stopping each trial timer.
+
 ## Suggested fix
 
 Cycle both resources that are fully overwritten each frame:

.github/issues/profile-optimized-sprite-builds.md

@@ -74,6 +74,16 @@ make flame FLAME_EXAMPLE=crowd
 make flame FLAME_EXAMPLE=crowd FLAME_ODIN_FLAGS="-debug -o:none"
 ```
 
+Reproduce the isolated build-mode comparison with the committed CPU harness:
+
+```bash
+make perf-draw PERF_ODIN_FLAGS="-debug -o:none"
+make perf-draw PERF_ODIN_FLAGS="-debug -o:speed"
+```
+
+Both runs print the Git commit, Odin version, compiler flags, every trial, and
+the median nanoseconds per draw.
+
 Consider applying an explicit optimization mode to performance-oriented example
 runs as well. Plain `odin run` currently uses Odin's unoptimized default.
 

.github/issues/prototype-instanced-sprite-rendering.md

@@ -39,6 +39,22 @@ The paired benchmark used ten order-alternated samples of 400 frames:
 Instancing improved median frame time by approximately **1.1%** on
 Vulkan/Lavapipe with 128 sprites.
 
+## Reproduction harness
+
+Run the committed visible full-frame workload on baseline and candidate commits:
+
+```bash
+make perf-frame \
+	PERF_FRAME_SCENARIO=0 \
+	PERF_FRAME_SPRITES=128 \
+	PERF_ODIN_FLAGS="-debug -o:speed"
+```
+
+Keep all other `PERF_FRAME_*` values unchanged and compare
+`median_ms_per_frame`. To test 512 or more sprites, first raise the engine's
+`MAX_SPRITES` and associated buffer capacities on the candidate branch, then
+set `PERF_FRAME_SPRITES` to the same value.
+
 ## Suggested fix
 
 Treat this as a prototype gated by larger sprite counts or a demonstrated

.github/issues/simplify-draw-sprite-clip-math.md

@@ -55,6 +55,18 @@ Environment:
 - Optimized with `-debug -o:speed`
 - Linux x86-64
 
+## Reproduction harness
+
+Run the committed CPU harness on the baseline commit and again after applying
+the suggested fix:
+
+```bash
+make perf-draw PERF_ODIN_FLAGS="-debug -o:speed"
+```
+
+Keep `PERF_DRAW_ITERATIONS`, `PERF_DRAW_WARMUP`, and `PERF_DRAW_TRIALS`
+unchanged between commits. Compare `median_ns_per_draw`.
+
 ## Suggested fix
 
 Compute clip scaling once and construct corners from the unique coordinates:

Makefile

@@ -16,6 +16,7 @@ FLAME_PREFIX := $(FLAME_OUT_DIR)/$(FLAME_EXAMPLE)-$(FLAME_STAMP)
 PERF_DRAW_ITERATIONS ?= 2000000
 PERF_DRAW_WARMUP ?= 10000
 PERF_DRAW_TRIALS ?= 7
+PERF_ODIN_FLAGS ?= -debug -o:speed
 PERF_FRAME_SPRITES ?= 128
 PERF_FRAME_FRAMES ?= 400
 PERF_FRAME_WARMUP ?= 100
@@ -71,13 +72,19 @@ check:
 	odin check examples/clips -collection:pkg=.
 
 perf-draw:
-	odin run benchmarks/draw_sprite -collection:pkg=. -debug -o:speed \
+	@echo "git_commit=$$(git rev-parse HEAD)"
+	@echo "odin_version=$$(odin version)"
+	@echo "odin_flags=$(PERF_ODIN_FLAGS)"
+	odin run benchmarks/draw_sprite -collection:pkg=. $(PERF_ODIN_FLAGS) \
 		-define:PERF_ITERATIONS=$(PERF_DRAW_ITERATIONS) \
 		-define:PERF_WARMUP=$(PERF_DRAW_WARMUP) \
 		-define:PERF_TRIALS=$(PERF_DRAW_TRIALS)
 
 perf-frame:
-	odin run benchmarks/sprite_frame -collection:pkg=. -debug -o:speed \
+	@echo "git_commit=$$(git rev-parse HEAD)"
+	@echo "odin_version=$$(odin version)"
+	@echo "odin_flags=$(PERF_ODIN_FLAGS)"
+	odin run benchmarks/sprite_frame -collection:pkg=. $(PERF_ODIN_FLAGS) \
 		-define:PERF_SPRITES=$(PERF_FRAME_SPRITES) \
 		-define:PERF_FRAMES=$(PERF_FRAME_FRAMES) \
 		-define:PERF_WARMUP_FRAMES=$(PERF_FRAME_WARMUP) \