performance-forensics

name	performance-forensics
description	Read-only measured performance diagnosis for latency, CPU, throughput, I/O, contention, traces, or hillclimbing. Improvement is a Ground or Verify method inside a caller-owned mutation lifecycle. Use memory-profiler for leaks, OOM, or heap fragmentation.
license	Complete terms in LICENSE

Performance Forensics

Use this skill for empirical performance diagnosis and optimization. Performance engineering requires measurement artifacts instead of speculative code inspection.

For memory leaks, out-of-memory errors, and heap fragmentation, use memory-profiler.

Modes of Operation

Select the mode that matches the task trigger:

• Live process diagnosis: Inspect active spinning processes, thread contention, or I/O stalls. Read references/runtime-forensics.md.
• Static trace diagnosis: Analyze captured profiles, CPU dumps, spindumps, and traces. Read references/trace-forensics.md.
• One-off optimization: Resolve a specific latency, throughput, or CPU bottleneck. Read references/perf-issue.md.
• Iterative hillclimbing: Optimize a metric across multiple experimental cycles. Read references/hillclimb.md.

Diagnosis Workflow (Read-Only Default)

Diagnosis tasks are read-only by default. Do not mutate production code during diagnosis unless requested.

1. Capture evidence. Obtain a CPU profile, trace, or execution log using a realistic workload.
2. Reduce artifacts. Query the profile to identify the dominant bottleneck or hot call tree.
3. Confirm the mechanism. Verify the bottleneck on the running target before proposing changes.
4. Attribute to source. Map the hotspot to the exact file, symbol, and line number.
5. Report findings. Provide the diagnosis, source location, and artifact paths.

Optimization Workflow

When authorized to mutate code, follow this measurement loop:

1. Ground the workload. Define a representative workload matching real input distributions.
2. Establish baseline. Capture baseline metrics and profile artifacts. Save the artifact path.
3. Formulate single hypothesis. Pick a targeted strategy from the eight strategy families in references/perf-issue.md.
4. Apply isolated change. Modify only the code related to the selected hypothesis.
5. Measure post-fix result. Run the identical workload. Compare the new artifact against baseline.
6. Evaluate outcome. Keep confirmed improvements. Restore only experiment changes owned by this run after regressions or neutral results. Flag inconclusive measurements.
7. Iterate or stop. For sustained optimization, follow the stop rules in references/hillclimb.md.

Reporting Contract

For diagnosis, return the workload, baseline artifact, source attribution, and status. For authorized optimization, also return:

• Workload description and parameters.
• Post-fix measurement number and artifact path.
• Net delta percentage or throughput difference.
• Status classification: improvement, regression, or inconclusive.

Attribution

Adapted from upstream pstack performance and forensics playbooks. See LICENSE.