surface-benchmarker

Surface Benchmarker Skill

This skill provides guidelines for AI agents to run and interpret performance benchmarks for the Hex1b Surface API. Run benchmarks whenever you modify code in src/Hex1b/Surfaces/ to ensure performance is not regressed.

Quick Reference

Action	Command
Run all Surface benchmarks	dotnet run -c Release --project benchmarks/Hex1b.Benchmarks -- --filter "Surface*"
Run specific benchmark	dotnet run -c Release --project benchmarks/Hex1b.Benchmarks -- --filter "*WriteText*"
Quick dry-run (sanity check)	dotnet run -c Release --project benchmarks/Hex1b.Benchmarks -- --filter "Surface*" --job dry

---

When to Run Benchmarks

ALWAYS run benchmarks after modifying:

File/Area	Critical Benchmarks
SurfaceCell.cs	All (cells are used everywhere)
Surface.cs	CreateSurface_*, WriteText_*, Fill_*, Clone_*
CompositeSurface.cs	CompositeSurface_*
SurfaceComparer.cs	Compare_*, ToTokens_*, ToAnsiString_*
SurfaceDiff.cs	Compare_*
ComputeContext.cs	CompositeSurface_* (computed cells use this)

---

Benchmark Harness Architecture

Project Structure

benchmarks/Hex1b.Benchmarks/
├── Hex1b.Benchmarks.csproj    # Console app with BenchmarkDotNet
├── Program.cs                  # Entry point
└── SurfaceBenchmarks.cs        # Surface API benchmarks

How BenchmarkDotNet Works

BenchmarkDotNet is a .NET performance benchmarking library that:

1. Warms up the JIT by running the benchmark multiple times before measuring
2. Runs multiple iterations to get statistically significant results
3. Reports mean, median, standard deviation for each benchmark
4. Tracks memory allocations (when [MemoryDiagnoser] is enabled)

Benchmark Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│ 1. GlobalSetup                                                  │
│    - Runs once before all benchmarks                            │
│    - Creates pre-allocated surfaces, diffs, etc.                │
│    - Sets up shared test data                                   │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. For each [Benchmark] method:                                 │
│    a. Warmup phase (JIT compilation, cache warming)             │
│    b. Pilot phase (determine optimal iteration count)           │
│    c. Actual measurements (multiple iterations)                 │
│    d. Results aggregation                                       │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Report Generation                                            │
│    - Console output with statistics                             │
│    - Optional: HTML, CSV, JSON exports                          │
└─────────────────────────────────────────────────────────────────┘