AGENT SKILL

perf-issue

Measured performance work. Use when the user asks to make something faster or use less memory or CPU, or asks why it is slow.

License 许可
MIT
所属仓库
syanga/astack
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
perf-issue
description
Measured performance work. Use when the user asks to make something faster or use less memory or CPU, or asks why it is slow.

02 资源文件 2

03 SKILL.md 正文

Perf issue

You own the measurements. Plan, review, verify the numbers. Tie every fix to a measurement.

When the user asks for sustained improvement against a metric, such as iterating toward a target, use hillclimb. Pass the workload, target, baseline evidence, traced model, measurement command, correctness checks, delivery scope, and existing authorization. Hillclimb then owns the repeated experiments, stopping criteria, and delivery.

For a diagnosis-only request, stop before implementation with the measurements, supported cause, and proposed next experiment. A read-only request also excludes instrumentation and code edits.

  1. Read scale the workflow before anything else in this skill.
  2. Reproduce the reported problem in an authorized environment and capture a baseline through the affected UI, CLI, or API. Name the metric, unit, target, workload, revision, configuration, and repeatable command. Without a target from the user, use the metric value at which the complaint no longer reproduces. Record warmup, trial count, and variation so later comparisons can distinguish a change from noise. Vet the baseline, and each later number, with the benchmark checklist. When the fix under test is a setting, such as an index or batching, keep that setting at production's current value on the baseline, and tune every other setting. For live capture and mechanism checks, follow runtime forensics. For an existing capture, follow trace forensics. For a diagnosis-only request, the capture can replace the live baseline. For a regression, also measure a known-good revision, and bisect to the change that slowed it. If the baseline does not reproduce the complaint, report the gap before optimizing.
  3. Use how to ground hypotheses, unless you already hold a traced model of the hot path. Measure the workload before claiming a performance limit. Most fixes come from eight strategy families. Try them in order, cheapest first. A family earns an attempt only when the trace shows the signal it names. When an earlier family meets the target, stop.
    1. Elimination. Before optimizing the hot path, ask whether it needs to exist: a computation nobody consumes, a feature gate that's always off for this user, a sync that redundantly mirrors state, a legacy path kept "just in case". The trace shows what's slow, never that it's deletable, so this family needs the traced model from this step, not the profiler.
    2. Caching. The same computation or fetch repeats on identical inputs. Store and reuse the result. Name what invalidates it before claiming the win.
    3. Batching. Many small operations each pay a fixed overhead (RPC, query, syscall, draw call). Coalesce them to pay the overhead once per batch.
    4. Lazy evaluation. Cost lands on results that are never used or not needed yet (eager init on the boot path, rendering offscreen items). Defer the work until first use.
    5. Scheduling. The work must happen, but not during the interactive moment. Move it to where nobody is waiting: idle callbacks, a background warmup after boot, precompute before the user arrives, cleanup after the frame commits. The win is perceived latency, so measure the interactive path, not total work done.
    6. Divide and conquer. The dominant cost scales with input size. Split the work so each piece touches less (chunk, shard, prune the search space) or so independent pieces run in parallel.
    7. Redundancy. The wait hangs on one slow instance or attempt. Duplicate the work (replicas, hedged requests, speculative execution) and take the fastest result. The trace has to show the wait dominates and the system has headroom.
    8. Indirection. The hot path does expensive work a cheaper intermediate could absorb: an index instead of a scan, a queue that shifts work off the interactive thread, a handle that lets a cheaper implementation swap in. Add the hop only when it removes more from the critical path than it adds.
  4. Plan the fix from the measurements. If it crosses a function boundary, read architect first. When you delegate the fix, give the worker the hypothesis, scope, fixed workload, measurement command, and correctness checks. Review the diff and capture post-fix measurements. Apply sequence-verifiable-units, verifying each attempt before trying the next. Remove rejected experimental changes while preserving unrelated work.
  5. Parse and compare the artifacts using the same workload, environment, metric, and measurement method. Change the code revision under test, and record both revisions. Report the absolute and percentage delta with the observed variation. Run correctness checks, using tdd when adding a behavioral regression test. An inconclusive measurement or a measurement of a different interaction is not a pass. Remove temporary instrumentation or record why it remains and who owns cleanup.
  6. End with review-pr in fix-and-review mode against the revision the fix started from. Run it for every fix, however small. Its reviewers are independent of you, so reviewing the diff yourself does not replace it. When the task's delivery scope includes a PR, use open-pr instead, which ends with review-pr. When a PR exists, cite the commands, results, and artifact paths under its ## Verification. Merging is a separate action.

For a unit in a multi-phase plan, follow the shared execution-state convention. Reuse its store. For a session transfer, read handoff and include the measurement command, workload, results, and artifact paths.

Reply: verdict, metric, baseline number, post-fix number, delta, variation and run count, limiter, whether the target was met, correctness checks, and artifact paths.

04 同仓库更多 Skills