superzip-performance

name	superzip-performance
description	Validate SuperZip CPU/GPU performance, RAM-only benchmarks, compression-level/block-size tuning, and AMD HIP telemetry without causing SSD wear. Use when changing benchmark scripts, compression levels, compression block sizes, worker allocation, GPU utilization, performance docs, or performance claims.

SuperZip Performance Skill

Read docs/performance-block-size-validation.md, docs/compression-level-and-benchmark-suite.md, and docs/gpu-accelerated-ui-and-codec-research.md before editing performance code, benchmark scripts, compression-level UI, block-size UI, GPU/UI performance architecture, or benchmark documentation. Run tools/verification_plan.ps1 -IncludeUntracked before choosing checks. The plan marks RAM-only benchmark sweeps as manual commands when performance code or performance claims are touched. For pushed performance changes, use opportunistic GitHub Actions checks only during iterative tuning when workflowWaitPolicy.deferAllowed=true; run the final relevant workflow wait before recording a completed tuning result.

Required rules:

• CPU/GPU comparison benchmarks must use tools/bench.ps1 in default memory-only mode.
• The benchmark must report memory_only=true and disk_write_bytes=0 for every forced-CPU and required-AMD-HIP lane.
• Sweep all production block sizes when validating performance: -BlockSizeKiB 256,512,1024,2048,4096,8192,16384.
• Compare CPU and GPU at the same compression level and report compression ratio, input bytes, and output bytes. Level 5 is the standard balanced release baseline.
• Native .suzip required-GPU ratio work must stay on GPU-native block kinds. Version 3 may emit adaptive GPU-prefix blocks at stronger levels, but agents must not describe this as CPU Deflate/Zstd or as a fallback path.
• Do not run or reintroduce multi-GB filesystem benchmarks during development. Use tools/storage_smoke.ps1 or the 64 MiB-capped filesystem smoke only for archive write/read correctness.
• Required-GPU benchmark lanes must fail if HIP is unavailable. Do not count CPU fallback telemetry as GPU work.
• Propagate verified benchmark improvements into production code paths. Do not keep benchmark-only optimizations.
• The System page GPU graph and headline value are total system GPU engine utilization from OS counters. VRAM total and SuperZip dedicated VRAM are detail rows only; do not use VRAM percentage or process-only GPU samples as the graph source.
• Do not change System graph history length, sampling cadence, or horizontal progression while fixing labels or counter semantics unless the task explicitly asks for graph-cadence work.
• Do not treat GPU-rendered UI, Direct2D/Composition work, or visual polish as evidence of archive GPU acceleration. Archive acceleration claims require required-HIP codec telemetry and RAM-only CPU/GPU comparisons.
• Dramatic GPU performance work must target batched, bounded, asynchronous HIP codec execution, not benchmark-only changes. Any pinned host memory, persistent device workspace, stream, HIP graph, or rocPRIM change must prove bounded RAM/VRAM use and pass the full Mixed/Compressible/Incompressible 10 GiB memory-only profile sweep before release claims.

Standard manual command after plan-selected correctness tests pass:

tools/bench.ps1 -Configuration Release -SizeMiB 10240 -Profile Mixed -CompressionLevel 5 -Iterations 1 -BlockSizeKiB 256,512,1024,2048,4096,8192,16384
build/Release/superzip_cli.exe benchmark-suite --profile Mixed --compression-level 5 --tune

Record CPU/GPU throughput, worker counts, HIP chunk counts, HIP kernel launches, HIP event time, transfer bytes, allocation bytes, input bytes, output bytes, compression ratio, and benchmark score for every block size. Do not make "much faster" or "order-of-magnitude" claims unless the recorded speedup proves that exact statement on the same workload, level, and ratio basis.