skills/skills/kvb-code-tune/SKILL.md

---
name: kvb-code-tune
description: >
  Speed up CI, deploys, builds and hot paths without losing logic or
  coverage. Trigger on /kvb-code-tune, a job hitting its time budget, or
  asked where time goes.
---

# Tune

One rule outranks every optimization: **nothing that reduces logic, coverage or
correctness counts as a speed-up.**

## Once per session: listen first

The first time this skill runs in a session, invoke the `kvb-think-listen`
skill before measuring anything, and ask three questions through the host's
structured question mechanism. Offer each as a checklist (multi-select) with
suggestions, and allow free text:

1. **What to examine.** Suggestions: CI wall-clock, deploy duration, gate and
   test runtime, image pulls and build caches, per-item loops and process
   spawns, idempotency (work repeated on a second run), network round trips,
   and resource use (CPU, memory, disk, I/O). Language, framework and
   recursion are checked on every run anyway (see Always check).
2. **Which performance boundaries to keep.** Suggestions: time budgets per job,
   deploy or gate; resource caps (memory, CPU, disk headroom); a minimum saving
   per change (default 10 s per run); the measurement source that counts as
   the verdict.
3. **Which limits apply to optimizations.** Suggestions: the scope that may be
   changed (files, roles, services); whether new dependencies, toolchains or
   languages may be introduced; whether infrastructure or CI configuration may
   change; the merge bar (default: the `kvb-org-split` skill's 90 % confidence and
   under 5 % break risk); a time cap per delegated agent (default 60 minutes).

Keep the answers for the rest of the session and do not ask again. Work only
inside them; a candidate outside them becomes a proposal.

When another skill (kvb-ci-triage, kvb-ci-observe) or an autonomous run invoked
this skill, skip
the questions: examine the handed-over log, apply the defaults above, and ask
only when an operator-only fact blocks.

## Forbidden, whatever it saves

- Dropping a test, a spec, a play, a drill or a verification pass.
- Raising a timeout or budget so a slow thing fits instead of getting faster.
- Swallowed failures, retry-until-pass, a soft skip, a narrowed assertion.
- Trading error semantics, credential masking, concurrency safety or a lint's
  intent for speed. A per-item failure stays loud and names its item.

A change that makes the clock smaller by testing less is reported to the
operator as a coverage cut for them to decide, never applied as a tuning.

## Measure first

Never tune what has not been measured, and read numbers from logs, not by eye.

- **Task profilers** (Ansible `profile_tasks` and similar) print the duration
  of the *previous* task under the *next* task's header. Pair each header with
  the following timestamp line, or read the end-of-run recap.
- **Build logs** (BuildKit): pair `#N [service x/y] RUN …` with `#N DONE Xs`
  by step number; `CACHED` marks a hit.
- **Gates**: per-target wall-clock tables and failed-target lines. An exit code
  piped through `tee` is not a verdict.
- **Code paths**: a profiler (py-spy, cProfile, perf, flame graphs) tells
  whether time goes to CPU, to I/O and waits, or to process start-up.
- Stream every run to a log file and compare runs by their logs; never re-run
  to recover a lost number.
- **Rank by fixed cost x count.** Measure the per-call fixed cost (one
  application console boot, one package-manager call, one container exec) and
  multiply by how often the run pays it. A one-second boot paid twenty-eight
  times is a candidate; a sixty-second download paid once is not.
- **The baseline is the newest log of the current code.** An older log may
  still carry the step a previous optimization replaced, and a saving measured
  against it is fiction.

## Invalid comparisons

Discard a before/after pair, not just its noise, when:

- Another gate, deploy or heavy job shared the machine during either run.
- The two runs differ in image or cache state. A cold build after a cache prune
  or a Dockerfile edit is expected: before calling a cold build a defect,
  compare the instruction text and the base image digest across both logs.
- One run pays a one-time cost (first install, migration, purge, model
  download) the other does not.
- A long wait hides retries or a failure; count retry lines before calling it
  slow.
- A fresh-install pass is compared with an update pass. Analyse each pass of a
  multi-pass run separately.

## Before you optimize

- **Search every branch** (the kvb-git-merge-fix skill's `find_fix.py -S <symbol> --path <path>`) for a change
  that already removes or reshapes the step. A fix on a sibling branch can make
  the whole candidate worth zero.
- A step that is long by design (a backup and restore drill, an end-to-end
  suite) is not a candidate. Its cost buys its guarantee.
- Apply the session's saving floor: a smaller saving is listed as "below
  floor" and dropped.
- Pruning build caches to free disk costs a cold rebuild of every custom image
  on the next run. Name that cost before anyone prunes.

## Coordinate every cost cluster

A cost cluster is one place the time goes: one step, one hot path, one
repeated call, named by its log line and its number. Before investigating or
implementing a cluster, run the `kvb-org-organize` skill's Peer protocol for it with
every agent session on this machine, not only the branch lineage.

- **The first to identify a cluster works it.** "First" is the `kvb-org-organize`
  claim `cluster/<slug>`, whose `--work` names the cluster's log line and
  number; between machines, the earliest announcement by message time. A
  claim without a measurement does not count. In the `kvb-org-rasci` register
  the cluster's key result is the measured target (`<step> from <before> to
  under <after>`), met only by the re-measurement.
- **Someone was earlier:** send them your measurements and findings, then move
  on to the next cluster. Never build a second optimization of the same
  cluster.
- **A claim ends** when its holder reports the result, a proposal or an
  abandoned attempt and releases it, or when the operator reassigns it.

## Always check

Every run examines these two on each measured hot path, whatever the operator
picked in the first question, and lists the result in the output table, a
clean result included:

- **Language and framework**: whether the hot path's language and framework
  are the most efficient fit for its work (see Language and framework).
- **Unnecessary recursion**: a recursive function that recomputes the same
  subproblem (memoize it or turn it into a loop), recursion that only walks a
  list or a fixed depth (a loop), a tree walk that visits or reads the same
  node more than once, depth that grows with the input (stack limits, Python's
  1000 frames), and recursive tool calls: a make target calling make, a role
  or playbook including itself, a script re-invoking itself per item. Count
  the calls first (a profiler's call graph, cProfile's `ncalls`, log lines);
  recursion that is bounded, rare and cheap stays.

## Levers that usually pay

- **Batch per-item process spawns**: N calls that each boot an interpreter or
  an application console become one process running N commands (one app
  console boot, one module, one batched API request). Keep each item's failure
  named and the exit code honest.
- **Skip no-op work** a previous step already did, such as a separate enable
  after an install that already enabled.
- **Idempotency flip-flops**: any `changed` on a second consecutive run.
- **Image pulls and builds**: pull only what the host lacks; keep build caches
  warm.
- **Overlap waits with work** only where concurrent execution is proven safe.
  Schema migrations and lock-holding steps are usually not.

## Language and framework

Check the language and the framework of every measured hot path, for example
replacing a Python hot path with Rust, or a heavy framework layer with a
lighter one or the standard library:

- **Only for measured CPU-bound work.** When the profile shows the time in
  computation inside the process (parsing, hashing, rendering, tight loops),
  a compiled language can win by an order of magnitude. When the time goes to
  process start-up, network round trips or waiting, batching in the current
  language wins first, and a rewrite changes nothing.
- **Framework overhead**: when the profile puts the time inside the framework
  (import and start-up, middleware, ORM query building, serialization),
  compare a lighter framework or the standard library on the same input. An
  ORM issuing one query per item is fixed by batching the query, not by
  swapping the framework.
- **Prefer the narrowest cut**: rewrite the hot function as an extension
  module (for Python and Rust: PyO3 and maturin) or a small binary behind the
  same interface, before rewriting a whole tool.
- **Count the total cost**: a toolchain in CI, builds per target architecture,
  shipping binaries to every host, the team's ability to maintain the code,
  and test parity with the old implementation.
- **Prove it on a prototype**: the same input, the same machine state, a before
  and an after number, and the old test suite passing against the new code.
- A language or framework change is applied only when the session's limits
  allow new languages, frameworks or toolchains; otherwise it is submitted as
  a proposal with the prototype's numbers.

## Delegating an optimization

Hand every optimization to an agent through the `kvb-org-split` skill: one sidetree
per candidate, branched from an exact commit, with a time cap and "measure
first, report the time split before implementing". The agent probes live
systems read-only and never starts gates or deploys. A broad brief without a
cap can run for hours without a word; at its cap, collect the agent's interim
findings and let it run on.

Before merging, run independent skeptics through the `kvb-think-dialectic` skill. The
antithesis must try to show that the candidate removes coverage, hides a
failure, or only moves the cost somewhere the measurement does not look.

## The loop

1. Measure, and name the single biggest cost with its log line and number.
2. Coordinate the cluster with the other agents; work it only when you
   identified it first, otherwise hand over your findings and take the next.
   Then form one candidate for it, after the branch search and the floor check.
3. Harden it with the `kvb-think-dialectic` skill.
4. Funnel it through a sidetree; merge what reaches the bar, submit the rest as
   proposals. Re-measure from the same source under the same conditions and
   report a before and an after number.
5. Repeat until the next candidate is worth less than the run that measures it.
6. Hand the prototypes and before/after harnesses of every kept candidate to
   the `kvb-code-transcend` skill, so the measurement stays in the repository
   as a benchmark or regression test.

## Output

One table, biggest saving first:

| Candidate | Before | After | Source | Verdict |

Rejected candidates stay in the table with the reason they fell: below floor,
coverage cut, outside the session's limits, invalid comparison, made moot by
another branch, or cap reached without a measured result. Proposals carry what
would close their gap.