@laitszkin/apollo-toolkit 3.12.1 → 3.13.1

package/iterative-code-performance/references/algorithmic-complexity.md

@@ -1,58 +0,0 @@
-# Algorithmic Complexity And Repeated Work
-
-## Signals
-
-Look for:
-
-- nested loops over growing inputs,
-- repeated full scans to answer point lookups,
-- repeated sorting when one sort or heap would do,
-- filtering or mapping the same collection in many branches,
-- recomputing derived values inside loops,
-- repeated parsing, validation, normalization, or conversion of identical inputs,
-- linear membership checks where sets or maps fit the domain,
-- duplicated business-rule computation across callers.
-
-## Safe optimization moves
-
-- Precompute lookup maps or sets at the smallest correct ownership boundary.
-- Move invariant computations out of loops.
-- Replace repeated scans with grouped data structures.
-- Sort once and reuse the ordering when the ordering contract is stable.
-- Convert repeated validation or normalization into a named helper with tests.
-- Preserve stable ordering when callers rely on it.
-- Keep data structures local unless shared ownership and invalidation are clear.
-
-## Complexity evidence
-
-Record:
-
-- current complexity and after complexity,
-- input sizes where the improvement matters,
-- any ordering, deduplication, or equality semantics,
-- memory tradeoff,
-- correctness guardrails.
-
-Do not claim a complexity improvement when the change only moves cost to another equally hot path.
-
-## Tradeoffs
-
-Prefer readability-preserving optimizations first. More complex data structures are justified when:
-
-- workload size is large enough,
-- call frequency is high enough,
-- the old implementation is measurably slow or asymptotically unsafe,
-- tests or invariants prove equivalence.
-
-Avoid clever micro-optimizations when the path is cold or the complexity cost is not material.
-
-## Correctness checklist
-
-Before and after complexity changes, verify:
-
-- duplicates are handled the same way,
-- stable ordering remains stable when required,
-- null, empty, malformed, and boundary inputs behave the same,
-- floating point, currency, timestamp, and locale semantics are unchanged,
-- errors and side effects occur in the same order when order matters,
-- public API and persistence contracts remain stable.

package/iterative-code-performance/references/allocation-and-hot-loops.md

@@ -1,53 +0,0 @@
-# Allocation And Hot-Loop Cleanup
-
-## Signals
-
-Look for hot paths that:
-
-- allocate new arrays, maps, regexes, formatters, buffers, or closures repeatedly,
-- clone, copy, or stringify large objects unnecessarily,
-- parse the same payload or date repeatedly,
-- build strings through repeated concatenation in loops,
-- perform expensive logging or serialization even when logs are disabled,
-- retain large intermediate objects longer than needed,
-- create short-lived promises or tasks in very tight loops.
-
-## Safe cleanup moves
-
-- Hoist invariant allocations out of loops.
-- Reuse existing parsed or normalized values.
-- Stream or chunk large data when repository patterns support it.
-- Avoid building debug payloads unless the log level or trace is enabled.
-- Replace repeated string concatenation with the project's idiomatic builder or join pattern.
-- Keep object reuse local and simple; avoid shared mutable pooling unless the codebase already uses it safely.
-
-## Memory tradeoffs
-
-Some optimizations reduce CPU by using more memory. Record:
-
-- maximum expected input size,
-- retained memory lifetime,
-- whether data is tenant/user/request scoped,
-- cleanup or eviction behavior,
-- effect on tail latency or garbage collection.
-
-Do not retain large data globally without a clear lifecycle.
-
-## Readability threshold
-
-Allocation cleanup may make code less direct. Accept that tradeoff only when:
-
-- profiler or benchmark evidence shows the path is hot,
-- the new code remains understandable,
-- comments or helper names explain non-obvious constraints,
-- tests preserve the behavior being optimized.
-
-## Validation
-
-Use:
-
-- allocation or memory benchmarks where available,
-- profiler allocation samples,
-- operation-count tests for avoidable repeated work,
-- regression tests for empty, large, duplicate, and malformed inputs,
-- end-to-end command/request checks when the hot loop affects public output.

package/iterative-code-performance/references/caching-and-memoization.md

@@ -1,64 +0,0 @@
-# Caching And Memoization
-
-## Use caching only when
-
-- the same expensive computation or read repeats,
-- the cached value has a clear owner,
-- invalidation or expiration rules are explicit,
-- stale data cannot violate business rules,
-- memory growth is bounded,
-- errors and partial results are handled deliberately,
-- benchmark or profiling evidence shows caching is worthwhile.
-
-## Prefer simpler fixes first
-
-Before adding a cache, ask:
-
-- Can repeated work be removed by computing once in the caller?
-- Can the data structure be reshaped locally?
-- Can the query or API call fetch all needed data in one pass?
-- Can a pure helper accept precomputed inputs?
-
-If yes, prefer the simpler change.
-
-## Cache design checklist
-
-Define:
-
-- key shape and equality semantics,
-- value ownership,
-- lifecycle and invalidation trigger,
-- maximum size or eviction policy,
-- concurrency behavior,
-- error caching policy,
-- observability for hit, miss, eviction, or stale detection when useful,
-- tests or benchmarks proving both correctness and value.
-
-## Memoization boundaries
-
-Good boundaries:
-
-- within one request, command, job, or transaction,
-- inside a pure helper for repeated identical inputs,
-- around immutable configuration or static metadata with reload semantics,
-- inside an owner module that already controls lifecycle.
-
-Risky boundaries:
-
-- global mutable caches with no invalidation,
-- cross-tenant or cross-user caches,
-- caches keyed by partial authorization context,
-- caches around time-sensitive, money, inventory, permission, or security decisions,
-- caches that hide external-service failures.
-
-## Cache removal
-
-Removing or narrowing a stale cache is a performance improvement when it:
-
-- prevents memory leaks,
-- avoids stale correctness risk,
-- reduces invalidation overhead,
-- improves tail latency by removing lock contention,
-- simplifies a path where hit rate is low.
-
-Validate both speed and correctness after removal.

package/iterative-code-performance/references/concurrency-and-pipelines.md

@@ -1,61 +0,0 @@
-# Concurrency And Pipeline Tuning
-
-## Signals
-
-Look for:
-
-- independent work performed serially on a critical path,
-- unbounded `Promise.all`, goroutines, tasks, threads, workers, or queue dispatch,
-- missing backpressure between producer and consumer,
-- retries that amplify overload,
-- locks, mutexes, transactions, or global caches causing contention,
-- long-running jobs that hold resources while waiting on slow IO,
-- pipeline stages with mismatched throughput.
-
-## Safe concurrency moves
-
-- Add bounded concurrency with existing project primitives.
-- Batch independent work while preserving ordering where required.
-- Push slow side effects behind existing queues only when delivery semantics remain the same.
-- Add cancellation, timeout, or backpressure only when consistent with current contracts.
-- Reduce lock scope or shared mutable state when the owner is clear.
-- Avoid parallelizing code that depends on side-effect ordering.
-
-## Backpressure and limits
-
-Define:
-
-- maximum concurrency,
-- queue size or batch size,
-- retry and timeout behavior,
-- downstream rate limits,
-- partial-failure handling,
-- ordering guarantees,
-- cancellation behavior.
-
-Do not introduce unbounded work in the name of throughput.
-
-## Correctness risks
-
-Concurrency changes can alter:
-
-- result ordering,
-- duplicate handling,
-- idempotency,
-- transaction boundaries,
-- retry timing,
-- log order,
-- shared test state,
-- resource cleanup.
-
-Add tests or controlled integration runs for the specific risk.
-
-## Validation
-
-Prefer:
-
-- deterministic unit tests for limiters and schedulers,
-- integration tests with fake slow dependencies,
-- operation-count or max-in-flight assertions,
-- load tests only when throughput or backpressure is the core claim,
-- logs or metrics that prove bounded behavior without leaking sensitive data.

package/iterative-code-performance/references/coupled-hot-path-strategy.md

@@ -1,78 +0,0 @@
-# Staged Strategy For Large Coupled Hot Paths
-
-## Purpose
-
-Teach the agent how to keep making progress when a performance-sensitive file feels too central, too coupled, or too risky to optimize directly.
-
-The correct response is usually not "stop". The correct response is "find the next unlock step".
-
-## Core rule
-
-A large coupled hot path is a **decomposition and measurement signal**, not a **completion blocker**.
-
-If a safe, behavior-preserving unlock step exists under current guardrails, take that step now instead of deferring the whole area.
-
-If measurement or correctness guardrails are too weak for direct optimization, strengthening them is itself the next unlock step.
-
-## First questions to ask
-
-When a hot path feels untouchable, ask:
-
-- Which part is actually slow, and how do we know?
-- Which work is pure computation, IO, allocation, synchronization, or side effect?
-- Which workload shape, input size, or data distribution matters?
-- Which behavior can be locked down with characterization tests?
-- Which benchmark or profiler hook would isolate the bottleneck?
-- Which dependency seam can be introduced without changing behavior?
-- Which optimization would most reduce the cost of the next optimization?
-
-## Typical unlock sequence
-
-Pick one or more of these, in the order justified by current evidence:
-
-1. Add timing, profiling, benchmark, or characterization guardrails around current behavior.
-2. Extract pure transformations or workload-shape calculations.
-3. Name and isolate expensive repeated work.
-4. Separate query/IO preparation from pure decision logic.
-5. Introduce a narrow batching, lookup, or data-structure seam.
-6. Isolate cache ownership and invalidation decisions.
-7. Separate concurrency control from per-item business logic.
-8. Re-scan and decide whether a deeper optimization is now safer.
-
-## What not to do
-
-Avoid these anti-patterns:
-
-- declaring the area blocked just because it is important,
-- attempting a full hot-path rewrite before guardrails exist,
-- adding a cache because measurement is missing,
-- removing correctness checks to make the benchmark faster,
-- parallelizing side effects without proving ordering and idempotency,
-- escalating ordinary internal optimization into a fake macro-architecture concern,
-- mixing unlock work with unrelated style churn.
-
-## Choosing the next step
-
-Prefer the next step that maximizes:
-
-1. combined confidence from the agent's own ability, workload understanding, existing tests, benchmarks, or quickly addable guardrails,
-2. quality of performance evidence,
-3. leverage for future deeper optimization,
-4. reduction in repeated work, IO, allocation, or contention,
-5. low risk to current business behavior.
-
-If two steps are both safe, choose the one that makes the next iteration easier to measure or validate.
-
-If the file is high-risk and under-tested, prefer adding the smallest useful characterization or benchmark guardrails before attempting deeper edits. If the file is high-risk but well-guarded, do not stop only because the change is difficult; use the guardrails to validate the agent's work and repair any accidental breakage.
-
-## Completion rule for coupled hot paths
-
-Do not ask "Can I solve the whole file now?"
-
-Ask:
-
-- "Can I measure this path more accurately in the next iteration?"
-- "Can I make this path meaningfully cheaper in the next iteration?"
-- "Can I reduce repeated work, IO, allocation, contention, or cache risk right now?"
-
-If the answer is yes, continue iterating.

package/iterative-code-performance/references/io-batching-and-queries.md

@@ -1,55 +0,0 @@
-# IO Batching And Query Optimization
-
-## IO signals
-
-Look for:
-
-- N+1 database, network, filesystem, or external API calls,
-- repeated reads of the same file, config, secret, or remote resource,
-- chatty persistence writes that can be safely combined,
-- missing projection or over-fetching large records,
-- queries that load broad datasets then filter in memory,
-- serial external calls that are independent and can be bounded or batched,
-- retry loops that multiply downstream load.
-
-## Safe batching moves
-
-- Batch by the natural owner boundary and preserve per-item error reporting.
-- Use existing repository query builders, clients, and retry conventions.
-- Fetch only required fields when the API supports projection.
-- Push filtering, pagination, aggregation, or joins to the datastore only when semantics match.
-- Add bounded concurrency instead of unbounded fan-out.
-- Preserve idempotency, ordering guarantees, and partial-failure behavior.
-
-## Query shaping
-
-Before changing a query, identify:
-
-- source of truth and owner module,
-- expected row or document counts,
-- indexes or access patterns already documented,
-- transaction and consistency requirements,
-- pagination and sorting contract,
-- caller expectations around missing or duplicate records.
-
-Do not add indexes, migrations, or datastore-level changes unless the user scope and repository conventions support them.
-
-## External services
-
-For network and API paths:
-
-- respect provider rate limits and retry guidance,
-- avoid batching that exceeds request-size limits,
-- preserve timeout and cancellation behavior,
-- keep request IDs and correlation fields in logs,
-- use mocks, fakes, or recorded fixtures for tests when real services are not under test.
-
-## Validation
-
-Prefer guardrails that verify:
-
-- query or request count decreases,
-- result set and ordering are unchanged,
-- partial failures are reported the same way,
-- retries and timeouts still follow existing policy,
-- batching preserves per-item authorization and validation.

package/iterative-code-performance/references/iteration-gates.md

@@ -1,133 +0,0 @@
-# Performance Iteration Gates And Stopping Criteria
-
-## Pass discipline
-
-Each iteration must have:
-
-- a selected module or bounded module cluster,
-- a concrete performance target,
-- an explicit record of which performance job lenses were checked during the deep read,
-- a bounded file/symbol scope,
-- one or more selected execution directions,
-- baseline evidence or a reason measurement is unavailable,
-- a confidence assessment covering the agent's own ability to complete the optimization, the task's inherent difficulty, objective guardrail strength, benchmark quality, and rollback or repair paths,
-- expected behavior-preserving outcome,
-- validation plan,
-- rollback point if evidence contradicts the change.
-
-An iteration is not "one work type", and it also does not need to include every direction every time. Within the selected scope, choose the subset of directions that has the best current evidence and leverage: measurement, complexity, IO, caching, allocation, concurrency, and/or staged unlock work.
-
-Confidence is not a synonym for "easy". Assess whether the agent has enough understanding, skill, workload context, tests, benchmarks, validation commands, and recovery path to complete the optimization safely. A hard task can still be high-confidence when strong guardrails, characterization coverage, and clear rollback let the agent repair mistakes by making the guarded behavior green again.
-
-Avoid starting a broad second iteration before validating the first, but do not stop after a validated iteration if known actionable performance issues remain anywhere in the in-scope codebase.
-
-Do not stop after a validated iteration if any in-scope module remains unvisited in the module coverage ledger.
-
-## Validation cadence
-
-Run validation from narrow to broad:
-
-1. Formatter or type check for touched files when available.
-2. Unit tests for touched helpers and modules.
-3. Benchmarks, profiler runs, query-count checks, or operation-count checks for the optimized path when available.
-4. Integration tests for affected chains.
-5. Broader suite or build once multiple passes interact.
-
-If validation fails:
-
-- determine whether the failure is pre-existing, stale test expectation, flaky benchmark, test isolation issue, or real product bug,
-- fix the true owner,
-- keep regression coverage for real defects,
-- do not mask failures by weakening assertions or widening benchmark budgets without evidence.
-
-If validation passes and the performance plus correctness guardrails meaningfully cover the changed behavior, do not keep a known bottleneck in place purely because of subjective confidence concerns. Reassess whether the agent has enough capability and objective support to proceed; if yes, continue, and if no, choose the smallest measurement, benchmark, or unlock step that would make the next optimization credible.
-
-The final stopping condition also requires the relevant guarded test surface to be green; a partially red repository is not a completed optimization outcome.
-
-## Re-scan after each iteration
-
-Inspect the full known performance backlog for:
-
-- modules that are still unvisited or only shallowly read,
-- modules that were read but not yet checked against every available performance job lens,
-- new repeated work after moved or extracted concepts,
-- remaining N+1 calls, serial round trips, or excessive query shapes,
-- caches that are stale, unbounded, or unnecessary,
-- hot loops that still allocate avoidable objects,
-- concurrency changes that need backpressure or max-in-flight proof,
-- logs, metrics, traces, or benchmarks that now describe stale names or paths,
-- documentation or `AGENTS.md/CLAUDE.md` drift.
-
-Then choose the next execution directions with these priorities:
-
-1. strongest bottleneck evidence,
-2. largest user-visible or high-frequency impact,
-3. highest combined confidence from agent capability, workload understanding, correctness guardrails, benchmark quality, and recovery path,
-4. strongest leverage for later deeper optimization,
-5. lowest business-risk path toward broader system improvement.
-
-Use `references/job-selection.md` to convert those priorities into a concrete next-job choice.
-
-## Stage-gate after each iteration
-
-After every validated iteration, run a deliberate full-codebase decision pass:
-
-1. Re-scan the repository and refresh the known performance backlog.
-2. Refresh the module coverage ledger and identify unvisited in-scope modules.
-3. Ask whether any known in-scope actionable bottleneck still remains.
-4. If yes, decide whether it should be addressed in the very next iteration or whether measurement or unlock work is needed first.
-5. If the obstacle is a large, coupled, or central hot path, do not stop there; switch to staged unlock work and continue.
-6. Only declare the repository iteration-complete when the re-scan shows no remaining actionable in-scope bottleneck and no unvisited in-scope module except items that are explicitly deferred or excluded under the allowed stop categories.
-
-This stage-gate is mandatory. A validated local optimization does not by itself mean the repository is done.
-
-## Continue when
-
-Repeat the cycle when:
-
-- any known in-scope actionable performance issue remains unresolved,
-- any in-scope module remains unvisited,
-- measured slow paths remain,
-- clear algorithmic waste remains,
-- avoidable IO, query, or external-service round trips remain,
-- unsafe or low-value caches need removal or replacement,
-- allocation churn or hot-loop repeated work remains in a material path,
-- concurrency, backpressure, or batching gaps remain,
-- benchmarks or profiling are missing for a high-risk optimization that is otherwise actionable.
-
-Do not produce a final completion report while any item in this section is true. Continue with the next bounded iteration instead.
-
-## Stop when
-
-Stop only when there are no unresolved known in-scope actionable performance issues. Any remaining candidates must be explicitly classified as one of:
-
-- low-value micro-optimization,
-- speculative without concrete evidence,
-- production-measurement-only with no safe local proxy,
-- public contract migrations,
-- macro-architecture changes,
-- product behavior changes needing user approval,
-- blocked by unavailable credentials, unstable external systems, or missing documentation,
-- untestable with the current repository tooling and too risky to change safely.
-
-If a remaining candidate cannot be placed in one of these categories, it is still an actionable gap and the agent must continue iterating rather than complete the task.
-
-If an in-scope module has not received a performance deep-read iteration, it is still an actionable coverage gap even when the already-read modules look fast.
-
-## Completion evidence
-
-The final report should make the stopping point auditable:
-
-- passes completed,
-- execution directions selected per iteration,
-- module or module cluster covered per iteration,
-- performance job lenses checked per iteration,
-- final module coverage ledger,
-- stage-gate verdict after each full-codebase re-scan,
-- validation commands and outcomes,
-- confirmation that the guarded test surface is green after the optimization,
-- speedup, throughput, latency, CPU, memory, allocation, query-count, or complexity evidence,
-- behavior-preservation evidence,
-- docs and constraints sync status,
-- proof that the latest scan found no known actionable in-scope performance issues,
-- deferred items with reason and required approval, dependency, production data, or safety constraint.

package/iterative-code-performance/references/job-selection.md

@@ -1,92 +0,0 @@
-# Performance Job Selection Guide
-
-## Purpose
-
-Help the agent choose the next execution direction after each full-codebase performance re-scan.
-
-These are job-selection rules for Step 2 of the main skill loop. They are not workflow steps.
-
-The goal is not to force one permanent order. The goal is to choose the next job that most safely improves the selected module or module cluster and unlocks later work.
-
-Before choosing, the agent should first scan the selected module through every available performance job lens. Job selection happens after that scan; it is not a substitute for that scan.
-
-## Available jobs
-
-- measurement / benchmarking
-- algorithmic complexity / repeated-work cleanup
-- IO batching / query shaping
-- caching / memoization
-- allocation / hot-loop cleanup
-- concurrency / pipeline tuning
-- staged unlock work
-
-## Choose `measurement / benchmarking` when
-
-- the slow path is suspected but not proven,
-- multiple candidate bottlenecks compete and prioritization would otherwise be guesswork,
-- an optimization could regress correctness or user-visible latency without a baseline,
-- production symptoms exist but local reproduction or profiling is missing.
-
-## Choose `algorithmic complexity / repeated-work cleanup` when
-
-- nested loops, repeated scans, repeated sorts, or repeated filters dominate the path,
-- the same derived value is recomputed for every item or request,
-- a more appropriate data structure would reduce asymptotic or constant-factor cost,
-- the complexity change can be proven without changing business behavior.
-
-## Choose `IO batching / query shaping` when
-
-- N+1 database, network, filesystem, or external API calls exist,
-- serial round trips can be safely batched or preloaded,
-- query predicates, projections, pagination, or indexes are mismatched to real access patterns,
-- external calls lack timeout, retry, or result-shape handling that affects throughput.
-
-## Choose `caching / memoization` when
-
-- the same expensive pure or owner-scoped computation repeats,
-- cache ownership, invalidation, size bounds, and failure behavior are clear,
-- stale data cannot violate business rules,
-- a simpler repeated-work or data-structure fix is insufficient.
-
-## Choose `allocation / hot-loop cleanup` when
-
-- tight loops allocate avoidable objects, strings, buffers, regexes, or closures,
-- repeated serialization, parsing, cloning, copying, or formatting appears in a hot path,
-- memory pressure or garbage collection is part of the observed slowdown,
-- changes can preserve readability or are justified by strong hot-path evidence.
-
-## Choose `concurrency / pipeline tuning` when
-
-- safe independent work is unnecessarily serial,
-- current parallelism is unbounded or overloads downstream resources,
-- queues, workers, streams, or async tasks lack backpressure,
-- batching or bounded concurrency would improve throughput without changing ordering guarantees.
-
-## Choose `staged unlock work` when
-
-- the file feels too central or too coupled for direct optimization,
-- no safe full hot-path rewrite exists yet, but a preparatory step does,
-- you can reduce risk through measurement hooks, seam extraction, characterization tests, type extraction, data-shape clarification, or side-effect isolation,
-- the best next move is to make a future optimization cheaper rather than solve the whole area now.
-
-## Tie-breakers
-
-If multiple jobs are plausible, prefer the one that:
-
-1. addresses the highest-evidence bottleneck,
-2. improves the most user-visible or high-frequency path,
-3. increases safety for the next iteration,
-4. removes the strongest blocker to a deeper future optimization,
-5. helps an unvisited module reach performance deep-read coverage,
-6. matches the agent's self-assessed ability to understand, execute, benchmark, and repair the change under current evidence,
-7. preserves behavior with the clearest available guardrails.
-
-## Hard rule
-
-If performance evidence is too weak, `measurement / benchmarking` should usually win before code changes.
-
-If a high-risk hot path lacks enough correctness guardrails, benchmark or characterization guardrail work should usually win before a deeper optimization.
-
-If the area is difficult but the agent can explain the workload, behavior, affected contracts, rollback path, and available tests or benchmarks clearly, do not downgrade confidence just because the optimization is non-trivial. Strong guardrails mean accidental breakage should be repaired by returning the test and benchmark surface to green, not avoided by leaving an actionable bottleneck in place.
-
-If any in-scope module remains unvisited, choose jobs that help the next highest-evidence or easiest useful unvisited module become deeply read, improved, or validated-clear before spending another round on already-familiar areas.

package/iterative-code-performance/references/measurement-and-benchmarking.md

@@ -1,78 +0,0 @@
-# Measurement And Benchmarking
-
-## Principle
-
-Optimize from evidence. A performance change should have at least one of:
-
-- production latency, throughput, CPU, memory, queue, or query evidence,
-- profiler output,
-- repeatable benchmark baseline,
-- test runtime profile,
-- log or trace timings,
-- clear algorithmic complexity proof tied to a plausible workload.
-
-If none exists, measurement is usually the next job.
-
-Measurement also informs confidence, but it is not the only input. The agent must assess its own ability to understand and complete the optimization, then combine that self-assessment with task difficulty, benchmark quality, correctness tests, rollback options, and repair paths. Strong tests and repeatable benchmarks should make difficult changes more actionable because failures can be diagnosed and driven back to green.
-
-## Baseline rules
-
-Before changing a hot path, record:
-
-- command, scenario, fixture, data size, seed, and environment,
-- current timing, throughput, allocation, query count, memory, or operation count,
-- variance or repeated-run notes when possible,
-- correctness oracle used with the benchmark,
-- reason if the path can only be measured in production.
-
-Do not compare a cold-cache baseline with a warm-cache after result unless that is the intended user-visible scenario.
-
-## Benchmark selection
-
-Use the cheapest reliable benchmark that proves the risk:
-
-- unit microbenchmarks for pure hot helpers,
-- integration benchmarks for query, serialization, or multi-module orchestration paths,
-- command or request benchmarks for user-visible entrypoints,
-- load tests only when concurrency, backpressure, or throughput is the actual risk,
-- profiler snapshots when the bottleneck location is unknown.
-
-Avoid expensive load tests when a deterministic benchmark or integration test proves the same performance issue.
-
-## Before/after comparisons
-
-A useful comparison names:
-
-- baseline command and result,
-- after command and result,
-- data shape and scale,
-- correctness validation,
-- variance or caveat,
-- whether the improvement is latency, throughput, CPU, memory, allocation, query count, or algorithmic complexity.
-
-If exact numbers are unstable, report operation counts, query counts, asymptotic complexity, or profiler rank change instead of pretending precision exists.
-
-## Guardrail design
-
-Performance guardrails should fail on meaningful regressions, not noise.
-
-Prefer:
-
-- deterministic operation or query counts,
-- bounded latency budgets with generous margins only when the environment is stable,
-- regression tests for duplicate work removal,
-- benchmark scripts documented for local use,
-- assertions on cache invalidation behavior,
-- profiler notes for manual verification when automated thresholds are unreliable.
-
-Do not add flaky timing thresholds to CI when the repository has no stable benchmark environment.
-
-## Production-only measurement
-
-When a bottleneck requires production data or credentials:
-
-- capture the best local proxy evidence available,
-- document the missing data source,
-- avoid speculative rewrites that cannot be validated,
-- add safe instrumentation or benchmark hooks if approved and useful,
-- classify the remaining item as production-measurement-only if no safe local action remains.