# Perf Fleet > Perf Fleet - Skill: `intense-visions/perf-fleet` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add intense-visions/perf-fleet` - Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/perf-fleet/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Intense-Visions (https://skillmd.com/u/intense-visions) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/intense-visions/perf-fleet --- # Perf Fleet > Autonomous performance-budget/regression remediation sweep — enumerate the perf-budget-violation and runtime-regression backlog by composing the existing perf detectors (`check_performance`, `harness check-perf`, the benchmark baselines), fold the codebase into independent remediation targets, rank them by severity value, confirm the batch with the human in one up-front round, fan out worktree-isolated subagents that each run the **real** per-target measure → remediate → re-measure pipeline gated by a measured before/after, independently verify every result by a re-measurement that proves the budget is met plus updated baselines plus all-OS CI, and hand back a tiered batch of perf-fix PRs and filed redesign issues for one bulk review. The fleet never auto-merges, never rebaselines a regression away, and never trusts a subagent's self-report. Working a performance backlog down by hand is a per-target attention slog: every budget violation and runtime regression must be found, its before-state measured, its remediation scoped, driven to a proven improvement, and turned into a reviewable PR — one at a time, with a human present throughout. For a codebase with dozens of hot paths and complexity hotspots the human's attention, not the machinery, is the bottleneck. `perf-fleet` inverts the model: it enumerates the backlog by composing the existing perf detectors, runs the real per-target pipeline autonomously and in isolation for each target, verifies the result against a re-measurement, and returns **perf-fix PRs to review in bulk** plus **filed issues** for the redesigns too large to auto-fix — moving the human from "remediate every regression" to "confirm the batch once, review the batch once." It is a **quality-queue** member of the `-fleet` family: it does not sit on the core intake → decide → build → land spine, but works the performance queue alongside it. The defining property is its verification bar. A performance "fix" that is not measured is a guess, and the cheapest way to make a red gate green is to move the goalpost — relax the budget or rebaseline the regression away. `perf-fleet` therefore holds a **measured before/after bar**, the perf analog of `bug-fleet`'s reproduction bar: a target is not remediated until a re-measurement against unmodified baselines proves the budget is now met. **No measured before/after, no fix** — and a "remediation" that only edited the baseline or the threshold fails that bar by design. This skill builds on the shared `-fleet` spine documented in `docs/reference/fleet-family.md` — the five-phase SELECT → CONFIRM → DISPATCH → VERIFY → terminal skeleton, the concurrency governor, the artifact + all-OS-CI verification discipline, the base-freshness clause, the worktree fan-out with its `.claude/`-nested push caveat, the per-leaf context-replay budget, the canonical `FleetHandoffRecord` handoff, and the never-silent-merge invariant. That page states the family contract once; this SKILL.md defines only what is `perf-fleet`'s own: its queue, its triage taxonomy, its per-target pipeline, its tiered terminal act, and its domain-specific rationalizations. ## Boundary — perf-fleet vs cleanup-fleet vs cicd-fleet The `-fleet` family already has two neighbours that touch performance-adjacent concerns; perf-fleet is scoped so it composes the detectors they share, never overlaps their queues: | Fleet | Queue it works | What it does NOT own | | --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `perf-fleet` | **measured perf-budget violations + runtime regressions** (bench/gate) | maintainability entropy with no measurement; a red CI run (that is the two neighbours) | | `cleanup-fleet` | code entropy / structural hotspots (dead code, drift, coupling) | whether a hotspot is a _measured_ perf-budget violation — that needs a benchmark | | `cicd-fleet` | CI/CD-red and flaky-test runs (a failure already manifested in CI) | a perf regression the gate has not yet caught, or a proactive budget sweep | The line is **the measurement bar**. A high-complexity function is `cleanup-fleet`'s when the goal is maintainability entropy; it is `perf-fleet`'s only when it is a **measured** perf-budget violation (a Tier-1/2 structural gate breach or a benchmarked runtime regression). A perf regression that has already turned CI red is `cicd-fleet`'s to heal from the red signal; `perf-fleet` proactively sweeps the budget/regression backlog and gates every fix on a fresh before/after measurement. perf-fleet composes `harness-perf` (which owns `check-perf` and the benchmark baselines) — it reimplements no perf measurement. ## When to Use - A performance backlog has accumulated (structural complexity/coupling budget breaches, benchmarked runtime regressions on hot paths, size-budget violations) and needs autonomous remediation plus one bulk review - Clearing performance debt across many independent hot paths where per-target interactive remediation does not scale - Turning the output of `check_performance` / `harness check-perf` / the benchmark baselines into a set of verified, scoped, merge-ready perf-fix PRs (and filed issues for the redesigns) in a single session - After a batch of merges that plausibly regressed performance across many modules at once - When the targets are genuinely independent — each is a distinct hot path or hotspot producing its own PR, and remediating one does not depend on another's merge - NOT for a single regression — invoke `harness-perf` (and `harness-debugging` for the fix) directly; a fleet's overhead only pays off across a batch - NOT for landing / merging PRs — that is `pr-fleet`; `perf-fleet` stops at merge-ready and never merges - NOT for enforcing the perf gate on one PR's diff — that is `harness-perf` inline; a fleet fans out across many standing targets, it is not a per-PR gate - NOT for maintainability entropy with no measurement — that is `cleanup-fleet`; perf-fleet works only the **measured** perf-budget/regression queue ## Flags | Flag | Effect | | --------------- | -------------------------------------------------------------------------------------------------------------------- | | `--concurrency` | Cap concurrent remediation subagents (default 2, max recommended 3 — the machine-storm limit) | | `--report-only` | Enumerate, score, and present the ranked target batch; do not dispatch, verify, or open PRs | | `--dry-run` | Run SELECT and CONFIRM only; stop before fan-out | | `--safe-only` | Restrict remediation to the safe fix class (file the risky redesigns as issues) even if a risky fix looks mechanical | ## Process ### Iron Law **A perf-fix PR is "merge-ready" only after an independent re-measurement proves the budget is met against unmodified baselines, plus all-OS-CI verification. The fleet never auto-merges, never applies a risky redesign autonomously, never rebaselines or relaxes a threshold to clear a violation, and never accepts a subagent's self-report as proof its pipeline ran.** A subagent that reports "optimized it — regression gone, CI green" has told you what it believes, not what is true. The only evidence that the real per-target pipeline ran and worked is the measured before/after it necessarily produces — the violation the target opened with (from SELECT) is re-measured **gone** against the same baselines — plus the CI signal on the pushed branch. If the re-measurement still shows the budget breached, the remediation did not land, regardless of how confident the report reads. And the cheapest fake green is the goalpost move: a "fix" that edited `.harness/perf/baselines.json` to match the new slower numbers, or relaxed a Tier threshold, is not a remediation — it is a suppression, and it fails the against-unmodified-baselines re-measurement by design. Landing the batch is the human's call: the fleet stops at a set of verified, reviewable PRs plus filed issues. ``` Phase 1: SELECT --> Phase 2: CONFIRM --> Phase 3: DISPATCH | v Phase 5: REPORT <-- Phase 4: VERIFY ``` | Phase | Purpose | Exit Condition | | ----------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | 1. SELECT | Compose perf detectors into targets, cross-check, score by severity value | Ranked `Target[]` with fix class, measured before-state, cross-check verdicts | | 2. CONFIRM | One up-front human round: approve/trim, confirm safe/risky calls, set cap | Human-approved batch with confirmed classes and agreed concurrency | | 3. DISPATCH | Worktree-isolated subagents run the real measure → remediate → re-measure per target | Every confirmed target returned a branch, filed, parked, or failed (recorded) | | 4. VERIFY | Independent before/after re-measurement + baseline-honesty + all-OS-CI, never self-report | Each returned target marked verified / rejected / retry | | 5. REPORT | One-row-per-target tiered summary (fix PRs + filed issues); never merge | Report delivered; risky redesigns filed with evidence for the human | ### Phase 1: SELECT — Compose Perf Detectors, Measure, Cross-Check, Score 1. **Enumerate the perf-budget/regression backlog by composing the existing detectors — reimplement no perf measurement.** Run and fold together: - `check_performance` — the current performance posture against defined budgets. - `harness check-perf --structural` and `--coupling` — complexity, nesting, size, and fan-in/fan-out budget breaches (Tier 1/2/3), and `get_critical_paths` for the hot-path set that carries the stricter thresholds. - the benchmark regression detector — `harness perf bench` compared against `get_perf_baselines` (`.harness/perf/baselines.json`), with the noise margin applied before flagging. - a git-churn pass over the perf-critical source (`git log --format=format: --name-only --since=...`) to surface hot paths whose code moved recently. Missing any one source degrades to whichever detectors are available; record which source was unavailable rather than aborting. If the project has no `.bench.ts` files, the benchmark tier is simply empty — the structural/coupling budget queue still stands. **Verify the toolchain first** (spine § _Runtime preconditions_): record the resolved `harness --version` and treat a stale scanner's findings as untrusted. 2. **Fold findings into remediation targets.** A **target** is one coherent hot path or hotspot cluster — the unit that becomes one PR (or one filed issue). Group co-located findings on the same function/module into a single target; never split a coherent optimization across PRs, and never bundle unrelated hot paths into one. 3. **Capture the measured before-state for every target.** A target enters the queue only with a **measured violation** recorded — the benchmark number vs its baseline (and the delta%), or the structural metric vs its threshold and tier. This before-state is the anchor VERIFY re-measures against; a target with no measurement is not a perf target, it is a maintainability finding (which is `cleanup-fleet`'s). 4. **Classify each target's fix class** by the remediation it needs: - **safe** (auto-remediated → fix PR): a bounded local optimization that provably meets the budget without changing public API or observable behaviour — an algorithmic fix in one function, removing an N+1 query, memoizing a hot computation, or an extract-method that lowers cyclomatic complexity below the threshold. - **risky** (filed as an issue for the human): a large or architectural redesign, a change on a correctness-sensitive hot path, or any optimization that alters a public API or observable behaviour. It is **filed with its measurement evidence attached**, never auto-applied — the perf analog of `bug-fleet` filing a risky-fix bug rather than patching it. 5. **Cross-check each target against merged and open PRs.** For every target, search merged/open PRs for one that already optimized that path. A target whose hot path was already remediated is **already-optimized** — flag it for drop/annotate, not re-remediation. (An open perf PR is a live claim; drop the target — see spine § _Cross-run claim lease_ for the ID-based-member mechanism, of which perf-fleet uses only the open-PR cross-check degradation, since a hot path has no GitHub-native id at SELECT.) 6. **Score and order by composite severity value.** Do not rank ad-hoc. Reuse `roadmap-pilot`-style impact scoring over a composite of **tier severity (Tier 1 > Tier 2 > Tier 3) × critical-path weight (a hot path outranks a cold one) × churn**, so the most severe regressions on the busiest hot paths come first and selection is principled and reproducible. 7. **Build the `Target` record** for each survivor: ``` Target { sources, // which detectors surfaced it (may be several) id, // target slug area, // function / module / hot path the target covers violation, // the measured before-state: metric vs threshold/baseline + tier + delta% fixClass, // "safe" | "risky" score, // composite severity-value score crossCheck, // "novel" | "already-optimized" resolvingPr, // set when crossCheck = already-optimized forks, // detected risky-redesign forks (may be empty) } ``` ### Phase 2: CONFIRM — The Single Up-Front Human Gate `[checkpoint:human-verify]` 1. **Present the ranked target batch in one round.** This is the **only guaranteed human touchpoint before review** — everything downstream runs autonomously. Present, together, in a single surface: - The ranked targets (highest-severity first) with scores and the **measured violation** each opens with (metric vs threshold/baseline, tier, delta%). - Each target's **safe / risky** fix classification — with risky targets flagged as they will **file an issue** (never auto-remediate). - Already-optimized targets **flagged for drop** with the resolving PR. - The **proposed concurrency** (default 2, capped at ~3). 2. **The human approves or trims once, and confirms the classifications.** Batch approval, safe/risky confirmation, and already-optimized triage all happen in this same gate — front-loading the genuinely-ambiguous calls is what keeps wrong-remediation rework low. A target the human downgrades to risky is filed rather than remediated. 3. **From here it is autonomous.** After this gate the fleet does not pause per-target. The only thing that re-surfaces to the human before REPORT is a target that turns out mid-flight to need a **risky** redesign (see DISPATCH) — and even that files only that one target without blocking the batch. Under `--dry-run` the skill stops at the end of this phase. ### Phase 3: DISPATCH — Worktree Fan-Out With a Concurrency Governor 1. **One worktree-isolated subagent per confirmed target, running the real measure → remediate → re-measure pipeline.** Each subagent is briefed to run the **real** per-target pipeline for its one target — it does not hand-optimize blind and it does not short-cut the pipeline; the measured before/after the pipeline produces is what VERIFY checks for: - **MEASURE** — establish the before-state on unmodified code with `harness-perf` (`harness perf bench` for a runtime regression, or `harness check-perf` for a structural budget breach). This must reproduce the violation SELECT recorded; a violation that does not reproduce is reported and the target dropped (a stale finding, never a fabricated fix). - **REMEDIATE** — drive the fix with the real fix skill for the target's cause: `harness-debugging` to diagnose and fix a runtime regression (the same diagnosis-and-fix pipeline `bug-fleet` uses), or `harness-refactoring` to bring a structural complexity/coupling breach under budget. The fix must be the safe class — bounded, and not altering public API or observable behaviour. - **RE-MEASURE** — re-run the same `harness-perf` measurement and confirm the budget is now met. Persist the new numbers with `update_perf_baselines` (`harness perf baselines update`) **only to record a genuine improvement** — never to move a red budget to match slower numbers. 2. **A target that needs a risky redesign files an issue; it never auto-remediates.** A subagent runs autonomously on the safe class for its target. But if meeting the budget turns out to require a **risky** change — a large/architectural redesign, a correctness-sensitive hot-path change, or a public-API/behaviour change — that target **files an issue with its measured before-state and a recommendation** instead of applying the fix. Filing is per-target: the other targets in the batch continue uninterrupted. The filed redesign appears in REPORT for the human. 3. **Cap concurrency at the governor (default 2, max ~3).** This is the machine-storm limit: beyond roughly three concurrent remediation agents the compound load produces flaky failures indistinguishable from real ones — **and it poisons the benchmark signal**, since a stormed machine's timings are noise, not measurement. Never exceed the confirmed concurrency to "go faster"; a benchmark run under load is worthless. Run each target's benchmark on a quiet machine with a clean working tree (`harness-perf`'s dirty-tree guard). 4. **Consult the per-leaf context-replay budget before fan-out.** A hot-path remediation can pull wide source context (a regression that spans several call sites). Estimate each leaf's context load and call `assertLeafWithinBudget` before dispatching it; an over-budget leaf is rejected loudly at dispatch, never silently spent. Assemble each leaf's working context **graph-scoped by default** (retrieve via `code_outline`/`get_critical_paths`/`find_context_for`, read raw source only for the region under optimization). See spine § _The per-leaf context-replay budget_. 5. **Record an "assumptions made" note per target.** Each subagent records the ranking basis, the remediation scope it took, the safe-vs-risky call it made, and the **before/after numbers with the noise margin applied**, so the eventual PR carries an assumptions note — batch review is only trustworthy when the reviewer can see the measurement, what was assumed, and what was deliberately left un-remediated. 6. **Push-path caveat.** A worktree created under a `.claude/`-nested path breaks the local pre-push gates (it self-excludes and scans zero files). Subagents push via the GitHub API or from a non-`.claude` throwaway worktree. **Never `--no-verify`** — bypassing the gate defeats the verification the fleet depends on. **Worker handoff — return the canonical `FleetHandoffRecord`.** When a worker finishes its target it hands the orchestrator exactly one `FleetHandoffRecord` (from `@harness-engineering/types`) — the ONE bounded envelope every `-fleet` member emits, so `fleet-command` parses any fleet's worker output uniformly instead of special-casing an ad hoc per-worker report shape. The record carries `status` (`done | parked | blocked | failed`), `fleet`, `item`, a one-line `summary`, an `evidence[]` of verifiable pointers (branch, PR, filed-issue number, baseline path, CI check — exactly the references VERIFY re-checks), `next_steps[]`, and, for any non-`done` status, a `blocker`. The measured before/after and the fix-class live inside the record's `summary`/`evidence`. The orchestrator validates it with `validateFleetHandoffRecord`; a malformed or unknown-keyed record is rejected, never silently misread. See the canonical handoff record in `docs/reference/fleet-family.md`. ### Phase 4: VERIFY — Independent Confirmation, Never Self-Report 1. **Never accept a subagent's self-report as verification.** "The regression is gone and CI is green" is a claim to be checked, not a result. For each returned branch, the orchestrator independently confirms the evidence itself. 2. **Require the measured before/after artifact against unmodified baselines.** Confirm the target actually improved: - The violation the target opened with (from SELECT) is **re-measured gone** — re-run the same `harness-perf` measurement on the branch and confirm the budget is now met. - The improvement is measured **against the baselines the target opened against**, not against a baseline the branch edited. Diff `.harness/perf/baselines.json`: a baseline update is legitimate only when it **records a faster number** for the target; a baseline moved to match a slower number, or a Tier threshold relaxed, is a **goalpost move** — reject it. A branch whose re-measurement **still shows the budget breached did not remediate** — regardless of what the subagent reported. Reject it (or retry once); it is never marked merge-ready. 3. **Require all-OS CI green.** Confirm the pushed branch's CI is green on **all target operating systems** plus the project's required checks (`gh pr checks` / `gh run list`), including the repo's own perf gate. Green on one OS is not green. A subset-red branch is not merge-ready — it is reported as failed, and the batch continues. **Base freshness (spine clause):** all-OS green is trusted as `verified` only when it ran against **current `main`** — the branch is up to date with `main`, or branch protection enforces strict / up-to-date-before-merge. Green gathered against a base `main` has since moved past is **stale** (and a perf baseline drifts as `main` churns): downgrade the item to **`degraded`**, not verified, and report the stale tested base SHA vs current `main`. See `docs/reference/fleet-family.md` § _Base freshness_ (`classifyBaseFreshness`). 4. **Classify each returned target** as `verified` (re-measured budget-met against unmodified baselines + all-OS CI green against a fresh base), `filed` (risky redesign, issue opened with evidence — not a PR), `rejected` (did not improve, or gamed the baseline, or definitively red), or `retry` (transient, retried at most once). No target reaches REPORT as merge-ready without passing both the re-measurement and the CI check. ### Phase 5: REPORT — Tiered Batch Summary, Never Merge 1. **Emit a one-row-per-target tiered batch summary** for bulk human review: | Target | Verdict | PR / Issue | Before → After | Findings resolved | Assumptions made | Filed redesign | | ------ | ------- | ---------- | -------------- | ----------------- | ---------------- | -------------- | Every verified target's row carries its PR link, the **before → after numbers** (with noise margin), the assumptions-made note from DISPATCH, and the tier it cleared. Filed targets carry their issue link and the recommendation. Rejected/failed targets are listed with the reason. 2. **The terminal act is tiered — fix PRs plus filed issues.** Verified safe-class targets are delivered as **merge-ready perf-fix PRs**; risky redesigns are delivered as **filed issues carrying the measurement evidence** (before-state, tier, recommendation) — the same tiered output `bug-fleet` produces (fix PRs for the bounded, filed issues for the risky). A filed issue is a first-class outcome, not a failure. 3. **Annotate already-optimized targets accurately.** For each target flagged already-optimized in SELECT and confirmed in CONFIRM, record it as dropped with a note **citing the resolving PR** — never a re-remediation. 4. **Never merge.** The fleet delivers verified, reviewable perf-fix PRs; the human (optionally via `pr-fleet`) lands the batch. Auto-merging a perf PR is out of scope by design — a subtly wrong optimization on a hot path is exactly where the one review the model is built around must happen. 5. **Degrade gracefully.** A missing detector source, an already-optimized target, or a single target's non-improving remediation results in that target (or source) being **reported** while the rest of the batch proceeds. One bad target never sinks the batch. ## Harness Integration - **`harness skill run perf-fleet`** — Run the full five-phase batch pipeline. - **`check_performance`** — Composed in SELECT to assess the current performance posture against budgets. - **`harness check-perf` (`--structural` / `--coupling`)** — Composed in SELECT for the structural/coupling budget queue; re-run in VERIFY as the independent structural re-measurement. - **`get_perf_baselines`** — Read in SELECT to compare benchmark results against the recorded baselines, and in VERIFY to diff the branch's baseline changes for goalpost moves. - **`update_perf_baselines`** — The only sanctioned way to persist new numbers; DISPATCH calls it to record a genuine improvement, never to mask a regression. Baselines are never hand-edited. - **`get_critical_paths`** — Composed in SELECT to weight hot paths (stricter thresholds) above cold ones in scoring. - **`harness-perf`** — The real measurement/benchmark pipeline each DISPATCH subagent runs for its before/after; the fleet composes it and never reimplements perf measurement. - **`harness-debugging`** — The real fix pipeline for a runtime regression with an investigable cause (the diagnosis-and-fix pipeline `bug-fleet` also uses). - **`harness-refactoring`** — The real fix pipeline for a structural complexity/coupling budget breach. - **`harness-roadmap-pilot`** — Its impact-scoring approach is reused in SELECT to order targets by composite severity value. - **`gh`** — Cross-check merged/open PRs (SELECT), read `gh pr checks` (VERIFY), open the perf-fix PRs and file the redesign issues (REPORT). - **`harness skill validate perf-fleet`** — The authoring-time gate for this skill's own structure and schema. - **`docs/reference/fleet-family.md`** — The shared `-fleet` spine this skill builds on (the five-phase skeleton, the concurrency governor, the per-leaf context budget, the artifact/CI verification discipline, the base-freshness clause, the worktree fan-out, the canonical handoff record, and the never-silent-merge invariant), stated once for the family. ## Success Criteria - Given a confirmed batch of N targets, the fleet produces **up to N** outcomes — perf-fix PRs for the safe class, filed issues for the risky class — each safe-class PR carrying a verified before/after re-measurement (budget met against unmodified baselines) and green CI across all target operating systems plus the project's required checks. - There is **exactly one** up-front human decision round; no per-target interactive pauses except a genuinely-risky redesign filed to its own target. - **Every emitted PR carries an "assumptions made" note** with the before/after numbers, the noise margin, and the ranking basis. - Risky redesigns are **filed with their measurement evidence, never auto-applied**. - Already-optimized targets are **dropped/annotated with a resolving-PR citation, not re-remediated**. - No target is marked merge-ready on a baseline edit or threshold relaxation — every verdict is a re-measurement against **unmodified** baselines. - The skill **never auto-merges** a perf-fix PR. - It **degrades gracefully**: a missing detector source or a single target's non-improving remediation is reported while the batch continues. - Concurrency never exceeds the confirmed governor (default 2, max ~3), and benchmarks run on a quiet machine with a clean tree. ## Gates - **No "merge-ready" without a verified before/after re-measurement.** A target whose re-measurement still shows the budget breached did not remediate. It is rejected or retried — never reported as merge-ready, no matter what the subagent claimed. - **No "merge-ready" without all-OS CI green against a fresh base.** Green on a subset of operating systems (or with the perf gate red), or green gathered against a base `main` has moved past, is not verified. Report subset-red as failed; downgrade stale-base green to `degraded` and refresh before it can authorize anything. - **Never move the goalpost.** Editing `.harness/perf/baselines.json` to match slower numbers, or relaxing a Tier threshold, is suppression, not remediation — it fails the against-unmodified-baselines re-measurement by design. Baselines are updated via `update_perf_baselines` only to record a genuine improvement. - **Never auto-apply a risky redesign.** Large/architectural redesigns, correctness-sensitive hot-path changes, and public-API/behaviour changes are **filed as issues** with the measurement evidence; the fleet applies only the safe class autonomously. - **Never auto-merge.** The fleet stops at reviewable PRs. Merging a perf PR from inside the fleet = gate violation; the human lands the batch. - **Never exceed the concurrency governor.** More than ~3 concurrent remediation agents is the machine-storm zone — and it poisons the benchmark signal. Do not raise the cap to "go faster." - **A self-report is never verification.** Accepting "regression gone, CI green" without independently re-measuring against unmodified baselines and checking CI = gate violation. Re-verify independently. - **Never fabricate a fix for an unreproducible violation.** If MEASURE cannot reproduce the SELECT violation on unmodified code, the finding is stale — drop the target and report it; never author a "fix" for a violation that does not exist. - **Never `--no-verify`.** No subagent bypasses the pre-push gates; a `.claude/`-nested worktree pushes via the GitHub API or a non-nested worktree instead. ## Escalation - **A detector source is unavailable (`check_performance` errors, no `.bench.ts` files, no baselines, no git history):** proceed with whichever detectors are available; record the missing source in REPORT rather than aborting. If no detector is available, stop and report — there is nothing to enumerate. - **MEASURE cannot reproduce the SELECT violation:** the finding is stale (the code already changed, or the scanner was out of step). Drop the target and report it as "did not reproduce" — never fabricate a fix. The batch continues. - **A subagent returns a branch whose re-measurement still shows the budget breached:** do not accept its self-report. Reject or retry once; if it still does not meet the budget, report the target as "did not improve" and move on — the batch continues. - **A target needs a risky redesign to meet the budget:** file an issue with the measured before-state and a recommendation; do not apply the redesign, and continue. The filed target is the only one affected. - **CI red on a subset of OS:** report the target failed with the failing OS/check named; never mark it merge-ready. Do not average a mixed CI result into "mostly green". - **The batch appears coupled (one target's optimization depends on another's merge):** stop fanning out those targets; the coupling means they are one convergence pipeline, not a fleet. Escalate to the human to sequence them. ## Rationalizations to Reject | Rationalization | Reality | | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "The subagent reported the regression is gone and CI is green, so the target is fixed" | A self-report is a claim, not evidence. Independently re-measure with `harness-perf` against the unmodified baselines and confirm CI — or the remediation did not land. | | "The benchmark baseline is stale anyway — just update it to the new numbers and move on" | Updating the baseline to match slower numbers is a goalpost move, not a fix. It fails the against-unmodified-baselines re-measurement by design; fix the regression. | | "The complexity threshold is a bit conservative — relax it for this one function" | Relaxing a Tier threshold to clear a violation is suppression. Bring the function under the budget (extract-method), or file the redesign — never move the line. | | "This regression is only 6% — it's probably just noise, ship it" | The noise margin (default 3%) is applied before flagging; a 6% regression on a critical path exceeds the Tier-1 bar even after noise. Measure, do not hand-wave. | | "This hot path needs a big architectural rewrite — I'll just do it while I'm in here" | A large/architectural redesign is the risky class. It is filed with its measurement evidence for the human, never auto-applied on a hot path. | | "I'll bundle every target's optimization into one big perf PR" | Scope one coherent target per PR. A mega-perf-PR is un-reviewable and un-revertible; the whole model depends on the reviewer holding one target's before/after in their head. | | "I'll hand-optimize this one target — it's faster than driving the whole pipeline" | Dogfood the real per-target skill. A hand-optimized target leaves no measured before/after, fails VERIFY, and breaks the guarantee that every PR ran the audited pipeline. | | "The SELECT finding is clear enough — I'll fix it without re-measuring the before-state" | No measured before/after, no fix. A violation that does not reproduce on unmodified code is stale; a fix with no before-state anchor cannot be verified. | | "The batch is verified — I'll merge these perf PRs to save the human a step" | Never auto-merge. A subtly wrong optimization on a hot path is exactly where the one review the whole model is built around must happen. | | "One target didn't improve, so the sweep is a bust — abort the batch" | Degrade gracefully. Report the non-improving target and keep the verified ones; one bad target never sinks the batch. | | "I'll reimplement the benchmark harness here so the fleet is self-contained" | Compose, don't reimplement. `harness-perf` owns `check-perf` and the baselines; a second measurement engine is drift waiting to happen. The fleet's value is orchestration. | ## Red Flags | Flag | Corrective Action | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | "I'll mark it verified based on the subagent's summary" | STOP. Independently re-measure the target against the unmodified baselines and check CI. A summary is not a verification. | | "The baseline is stale — I'll just bump it to green the gate" | STOP. That is a goalpost move. Re-measure against unmodified baselines; a baseline may only record a faster number. | | "This architectural rewrite looks safe enough — I'll apply it on the hot path" | STOP. Risky redesigns are filed with evidence, not applied. Record the before-state and a recommendation; do not auto-remediate. | | "Let me raise concurrency to get the benchmarks done faster" | STOP. A stormed machine poisons the benchmark signal. Cap at the governor and run benchmarks on a quiet, clean tree. | | "The pre-push gate is failing in this worktree — I'll `--no-verify`" | STOP. Never bypass. Push via the GitHub API or a non-`.claude` worktree; the gate is part of the verification. | | "All verified — let me merge and close the loop" | STOP. The fleet never merges. Deliver the PRs and filed issues for review; landing is the human's step. | ## Examples ### Example: A five-target perf-budget/regression sweep ``` $ harness skill run perf-fleet --concurrency 2 Phase 1: SELECT Composed detectors: check_performance -> posture: 2 budgets breached check-perf --structural -> serializeRoadmap() cyclomatic 18 (Tier 1, > 15) check-perf --coupling -> router.ts fan-out 13 (Tier 2) bench vs baselines -> parseDocument 4.2ms -> 4.9ms (+16.7%, critical path, Tier 1) churn pass -> both hot paths changed in the last 20 commits Folded into 6 targets; measured before-state captured for each; cross-check vs PRs: - "date-utils fast-path" -> already-optimized (merged PR: link) -> flag for drop Classified: 4 safe, 1 risky ("re-architect the document streaming pipeline") Scored 5 survivors by tier x critical-path x churn; ordered highest-first. Phase 2: CONFIRM [checkpoint:human-verify] Ranked batch (5) presented with each target's measured violation. Risky target "re-architect streaming" flagged as will-file (not auto-remediated). Human trims 1 low-severity Tier-3 target -> batch = 4 (3 safe + 1 risky). Concurrency: 2. Phase 3: DISPATCH (governor = 2) 3 safe targets: worktree-isolated subagents, 2 at a time, each running the real MEASURE (harness-perf) -> REMEDIATE (harness-debugging / harness-refactoring) -> RE-MEASURE. Risky target "re-architect streaming" -> files an issue with its before-state (+16.7% on parseDocument) and a recommendation; the other 3 continue. Phase 4: VERIFY (independent — no self-report) target A (parseDocument regression): re-measure 4.9ms -> 4.1ms (budget met), baseline diff records the FASTER number, CI green all 3 OS + perf gate -> verified target B (serializeRoadmap complexity 18): re-measure extract-method -> 11 (< 15), CI green all 3 OS -> verified target C (router.ts fan-out): re-measure STILL Tier 2 (fan-out 12) -> REJECTED (did not meet budget) target D (re-architect streaming): filed in DISPATCH -> issue link (risky, awaits human) Phase 5: REPORT | Target | Verdict | PR / Issue | Before → After | Findings | Assumptions made | Filed redesign | | ---------------------- | -------- | ---------- | ------------------ | -------- | ----------------------- | -------------- | | parseDocument regr. | verified | PR link | 4.9ms → 4.1ms | 1 | noise margin 3%; algo | — | | serializeRoadmap cx | verified | PR link | cx 18 → 11 | 1 | extract-method, no API | — | | router.ts fan-out | rejected | — | fan-out 13 → 12 | — | — | — (over budget) | | streaming re-architect | filed | Issue link | +16.7% (evidence) | — | — | streaming redesign | Dropped 1 already-optimized target with a note citing the resolving PR. Never merged. 2 fix PRs + 1 filed issue handed to the human for bulk review. ``` ### Example: Rejecting a goalpost move A subagent returns a branch and reports "done — regression …(truncated)