melodic-software Purpose
Answers "what should we optimize, and how much do we actually know about it?"
The failure this prevents is picking a target because its mechanism sounds expensive. Take a diagnosis of WDAC code-integrity enforcement as the cause of slow process spawns: the mechanism is real and the policy may genuinely be enabled, and it is still the wrong answer when the data says otherwise. A spread of min 180.5 ms / median 1107.7 ms / max 2841.3 ms across identical no-op spawns is a contention signature, because a fixed policy check cannot produce a 15x spread. The bimodality is the diagnosis; the plausible mechanism is a distraction.
So this skill ranks by evidence, and says so when there is none.
Inputs it accepts
| Source | What to do |
|---|---|
| The current session's own pain | Name the operation that felt slow and what was observed. Anecdote is a valid candidate source and an invalid ranking basis. |
| A named path or component | Enumerate the layers it spans before choosing one (see "Measure the layers first"). |
| A telemetry store | /claude-ops:observability for Claude Code's own; otherwise the project's. Prefer it over every other source. |
| Open-ended "what is slow here" | Widest scope, weakest evidence. Expect the output to be "instrument this first". |
Evidence tiers
Rank every candidate into exactly one. A lower tier never outranks a higher one, regardless of how compelling the mechanism sounds.
| Tier | Means | Example |
|---|---|---|
| E1, attributed measurement | A measurement that isolates this component's cost from its neighbours' | A spawn census showing this hook costs 4 of the 7 spawns per tool call |
| E2, aggregate measurement | A real measurement that includes this component but does not isolate it | "The whole pre-tool path takes 1.2 s" |
| E3, structural inference | No measurement; a documented cost model predicts expense | "This is a 125-line shell wrapper that runs per tool call" |
| E4, suspicion | A plausible mechanism and nothing else | "WDAC is probably slowing spawns" |
Nothing above E3 exists means the top recommendation is "instrument this first", naming the cheapest instrument that would reach E2. That IS the answer; do not substitute a ranked guess.
Measure the layers before choosing one
When a candidate spans layers (a shell wrapper around a Python program; a route through an ORM through a driver), attribute cost across the layers before picking one to optimize.
The instinct is to optimize the largest layer: a 1903-line Python guard body over the 125-line shell wrapper that execs it. Measurement routinely inverts that, and a wrapper this size can carry roughly 88% of the cost while the body it wraps is not the bottleneck. Layer attribution is cheap and reorders the candidate list.
Name the counter, not just the duration
For each ranked candidate, name the drift-immune counter that would settle it: process spawns, syscalls, queries, allocations, bytes, round trips. A counter is reproducible on a host whose wall clock is not.
If no counter exists for a candidate, say so explicitly. That is a real property of the target and
it changes what /performance:goal can promise.
Grounding: the counts-over-wall-clock rationale is stated in the literature for instruction counts specifically (Valgrind's Cachegrind manual; Iai). Extending it to spawns, syscalls and queries is this plugin's own generalization, not a sourced claim, and Valgrind's own manual argues the other side too: execution time "is a better metric than instruction counts because it's what users perceive". Present a counter as reproducible, never as more truthful.
Output
A ranked table, highest evidence tier first:
| Rank | Candidate | Tier | What is known | Counter that would settle it | Cheapest next instrument |
|---|
Then one line naming the recommended target and the tier it rests on. If that tier is E3 or E4, the recommendation is to instrument, not to optimize.
Boundary
- Does not set a goal or a target number. That is
/performance:goal, which is human-gated because it needs the floor computed and the realistic/ideal split agreed. - Does not measure. It ranks what is known and names what is missing;
/performance:snapshotcaptures. - Does not root-cause an observed failure. A specific broken or slow behavior with a reproduction is a debugging task, not a candidate ranking.
- Does not diagnose a slow Claude Code installation. That is
/claude-ops:audit-performance, which this skill consumes as a telemetry source rather than duplicating.
Next
/performance:goal <chosen target>. Carry the evidence tier forward: a goal built on an E3
candidate must say so.
Gotchas
- A plausible mechanism is not evidence. The WDAC diagnosis above is the worked example. Ask what the mechanism predicts, then check whether the data shows it. A fixed cost cannot produce a variable spread.
- Anecdote from this session is a candidate source, not a ranking basis. "It felt slow" gets a candidate onto the list at E4 and no higher.
- The biggest file is not the bottleneck. Line count is not a cost model. Attribute across the layers before believing size.
- A target with no drift-immune counter is a harder target, not an equal one. Say so here rather
than discovering it in
/performance:snapshotwhen a wall-clock claim gets refused.