Agent Skills › christopherkarani/Wax › wax-performance-audit

wax-performance-audit

GitHub

用于Wax仓库的性能基准测试与审计，诊断CPU、内存或I/O瓶颈及Swift并发问题。通过运行基准测试、隔离热点代码路径、对比基线与候选版本指标，定位性能回归并提供修复建议。

Resources/skills/public/wax-performance-audit/SKILL.md christopherkarani/Wax

Trigger Scenarios

需要评估代码变更对性能的影响排查延迟增加或内存泄漏等性能问题分析Swift并发相关的竞态条件或隔离风险

Install

npx skills add christopherkarani/Wax --skill wax-performance-audit -g -y

More Options

Non-standard path

npx skills add https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax-performance-audit -g -y

Use without installing

npx skills use christopherkarani/Wax@wax-performance-audit

指定 Agent (Claude Code)

npx skills add christopherkarani/Wax --skill wax-performance-audit -a claude-code -g -y

安装 repo 全部 skill

npx skills add christopherkarani/Wax --all -g -y

预览 repo 内 skill

npx skills add christopherkarani/Wax --list

SKILL.md

Frontmatter

{
    "name": "wax-performance-audit",
    "description": "Benchmarking and performance auditing for the Wax repo. Use when running or interpreting Wax benchmarks, diagnosing CPU, memory, or I\/O bottlenecks, or investigating Swift 6.2 concurrency issues such as Sendable, actor isolation, `@unchecked Sendable`, task-group fan-out, and data races."
}

Wax Performance Audit

Overview

Use this skill to benchmark Wax changes, isolate the hottest code path, and separate real regressions from noisy samples.

The repo builds with Swift 6.1 and StrictConcurrency enabled, so audit for Swift 6.2 concurrency risks without assuming 6.2-only language mode.

Workflow

Name the symptom precisely: latency regression, memory growth, file bloat, or Swift concurrency diagnostics.
Pick the narrowest benchmark or test file that exercises the path.
Run a baseline and candidate with the same environment and scale.
Collect wall time plus memory or file-growth metrics when the issue is not purely CPU-bound.
Inspect the smallest relevant actor boundary, task group, cache, or I/O path.
Report the evidence, the bottleneck, and the smallest safe fix.

Benchmark Selection

Use references/benchmark-workflow.md for the command matrix, environment flags, and benchmark map.

Prefer these repo entry points when they match the symptom:

Tests/WaxIntegrationTests/RAGBenchmarkSupport.swift
Tests/WaxIntegrationTests/RememberDedupBenchmarks.swift
Tests/WaxIntegrationTests/StoreBloatBenchmarks.swift
Tests/WaxIntegrationTests/RAGBenchmarks.swift
Tests/WaxIntegrationTests/RAGBenchmarksMiniLM.swift
Tests/WaxIntegrationTests/BatchEmbeddingBenchmark.swift
Tests/WaxIntegrationTests/SessionRuntimeStatsBenchmarks.swift
Tests/WaxIntegrationTests/WALCompactionBenchmarks.swift
Tests/WaxIntegrationTests/HandoffLookupBenchmarks.swift
Tests/WaxIntegrationTests/PayloadLivenessBenchmarks.swift
Tests/WaxIntegrationTests/SurrogateSourceBenchmarks.swift
Tests/WaxIntegrationTests/AccessStatsBootstrapBenchmarks.swift
Tests/WaxIntegrationTests/ConcurrencyStressTests.swift
Tests/WaxIntegrationTests/MemoryOrchestratorTests.swift
Tests/WaxArcticTests/ArcticPerformanceBenchmark.swift
Tests/WaxCoreTests/ReadWriteLockTests.swift
Tests/WaxCoreTests/AsyncMutexTests.swift

Bottleneck Triage

CPU: look for repeated serialization, unnecessary sorting, extra actor hops, and oversized batch work.
Memory: compare RSS, allocated bytes, dead payload bytes, TOC growth, and frame count.
I/O: inspect WAL compaction, reopen cost, and close-time rewrite work.
Embeddings: check compute unit selection, batch sizing, and warmup or prewarm behavior.
Noise: rerun if caches are cold, an external compiler/service is active, or the benchmark has low sample counts.
Gated skips: confirm the env flag actually enabled the lane before treating a skip or pass as evidence.
Harness plumbing: measureAsync in RAGBenchmarkSupport.swift uses DispatchSemaphore plus Task because XCTest measurement is synchronous; do not confuse that with production concurrency.
ANE/GPU: CPU-only benchmark paths are intentional in some suites, and warm p95/p99 values can be noisy when ANECompilerService or similar background work is active.

Swift 6.2 Concurrency

Use references/concurrency-checklist.md when the change touches actors, task groups, Sendable, or @unchecked Sendable.

Default checks:

Trace every value that crosses an actor boundary.
Prefer @Sendable closures that capture immutable values.
Treat @unchecked Sendable as a deliberate exception, not a default.
Watch task groups for hidden fan-out that increases memory pressure.
Keep blocking I/O off actor executors.
Verify @MainActor crossings in UI-adjacent or Photos code.
Treat @preconcurrency interop and @unchecked Sendable around CoreML, GRDB, Photos, and tokenizer internals as review hotspots, not automatic bugs.