| 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.
