@laitszkin/apollo-toolkit 3.12.1 → 3.13.0

package/version-release/SKILL.md

@@ -1,53 +1,33 @@
 ---
 name: version-release
-description: >-
-  用於明確的 semver 發版流程。必須先完成 `commit-and-push` 共用 gate 與
-  `submission-readiness-check`，再決定版本、更新 changelog、建立 tag、推送並發布 GitHub Release。
+description: 當你需要協助用戶完成版本發佈時，使用這個技能。
 ---
 
-# 版本發佈
-
-## Dependencies
-
-- Required: `commit-and-push`、`submission-readiness-check`
-- Conditional: `archive-specs`
-- Optional: 無
-- Fallback: 缺少必需技能時必須停止，不能憑印象手動補一個發版流程
-
-## Standards
-
-- Evidence: 以版本檔、`CHANGELOG.md`、本地/remote tag、既有 GitHub Release 與使用者明確的 bump 意圖作為依據
-- Execution: 先確認這真的是 release 請求，再完成所有 gate，之後才更新版本、切 changelog、打 tag、推送與發布 Release
-- Quality: 不猜版本、不重複發版、不用原始 diff 臨時拼 release notes；所有版本入口必須同步一致
-- Output: 交付可驗證的版本發佈結果，包含版本號、tag、remote驗證與 GitHub Release URL
-
 ## 技能目標
 
-把明確的發版需求轉成一條完整、可驗證、可追溯的 semver 流程，確保版本檔、changelog、git tag、remote狀態與 GitHub Release 彼此一致。
+幫用戶完成自動化版本發佈流程
 
 ## 驗收條件
 
-- 已先確認這是明確的 release / semver 請求；若只是 commit 或 push，必須改走 `commit-and-push`
-- 在修改任何版本相關檔案前，已清楚說出 current -> next 版本與將建立的 tag 字串
-- `submission-readiness-check` 與必要的 `archive-specs` 都已完成，且 `CHANGELOG.md` 的 `Unreleased` 內容足以支撐本次發版
-- 最終已同步版本檔、發布說明、commit、tag、remote refs 與 GitHub Release；若使用者明確要求不發布 Release，需在結果中清楚註明
+- `CHANGELOG.md`, `docs/` 下所有項目文檔已經被同步到最新狀態
+- Github release, Github version tag 被完成創建
 
 ## 工作流程
 
-1. 先確認使用者是否真的要求 release、publish、tag、patch、minor、major 或其他明確 semver 動作；若沒有，改用 `commit-and-push`
-2. 檢查目前 git 狀態、版本檔、既有 tag、本地與remote是否已有同版本 tag，以及 GitHub 上是否已有同版本 Release，避免重複發版
-3. 對 code-affecting 範圍執行 `submission-readiness-check`；若它要求 `archive-specs` 或 changelog/文件同步，必須先完成
-4. 根據版本檔、repo 歷史與使用者指示決定 current -> next 版本與 tag 格式；若語意不明，優先選較小 bump 並請使用者確認
-5. 一致更新所有版本入口，並把 `CHANGELOG.md` 的 `Unreleased` 移到新的版本區塊；release notes 只能來自整理過的 changelog 內容
-6. 建立 release commit 與 tag；若是 prerelease retarget，保留版本號不變，只把 tag / Release 移到新的 commit
-7. 推送分支與 tag，並驗證remote commit 與 tag 都已正確存在
-8. 使用 `gh release create` 或 repo 慣用工具建立或更新 GitHub Release，最後回報版本號、tag 與 release URL
+### 1. 檢查並確認 repo 狀態
+
+閱讀目前的 repo 狀態。查看是否依然存在未提交變更。如有，使用 `commit-and-push` 技能將目前為提交的變更暫存並提交。推送到 remote。
+
+### 2. 更新項目文檔狀態
+
+完整閱讀上一次發佈版本至今的所有變更，並檢查文檔之中的表述是否存在錯誤或遺漏。如有，使用 `align-project-documents`, `maintain-project-constraints` 這兩個技能將所有項目文檔同步到最新狀態。
+如果外部環境允許使用 subagents，建議通過調度subagents完成變更的逐行深度閱讀。
 
-## 使用範例
+### 3. 發佈版本
 
-- 「發 patch release」-> 先確認目前版本與 changelog，再更新到下一個 patch、建立 tag 並發布 Release
-- 「把 prerelease tag 移到最新修正」-> 不增加版本號，只重新對準 tag 與對應 Release
-- 「幫我 commit 然後 push」-> 不使用本技能，改走 `commit-and-push`
+確認所有文檔都已經被更新之後，更新 repo 的版本文件（如 pyproject.toml, cargo.toml）。
+使用 `commit-and-push` 技能將所有變更提交並推送到 remote。
+最後，將用戶要求的版本所對應的 version tag 推送到 remote 並建立 github release。
 
 ## 參考資料索引
 
@@ -56,4 +36,3 @@ description: >-
 - `references/branch-naming.md`：分支命名慣例
 - `references/changelog-writing.md`：`CHANGELOG.md` 與 `Unreleased` 維護規則
 - `references/readme-writing.md`：README 只在必要時同步更新
-- `commit-and-push`：共享的 git 檢查、提交與推送 discipline

package/iterative-code-performance/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 LaiTszKin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/iterative-code-performance/README.md

@@ -1,34 +0,0 @@
-# iterative-code-performance
-
-Improve an existing repository through a strict three-step loop of full-codebase performance scan, module-scoped optimization, and final documentation/constraint sync while preserving intended business behavior and the system's top-level macro architecture.
-
-## Core capabilities
-
-- Runs a repository-wide performance scan before every optimization round and refreshes a concrete bottleneck backlog.
-- Uses a strict three-step loop: scan the codebase, choose this round's jobs and optimize, then update docs/constraints only when no actionable gap remains.
-- Builds a module inventory and coverage ledger so every in-scope module receives a performance-oriented deep-read iteration before completion.
-- Defines deep-read as a job-oriented scan across measurement, algorithmic complexity, repeated work, IO, batching, query behavior, caching, allocation churn, hot loops, concurrency, and staged unlock opportunities.
-- Prioritizes measured or clearly complexity-backed bottlenecks over speculative micro-optimizations.
-- Adds or updates benchmark, characterization, regression, load, or integration guardrails when optimization risk requires them.
-- Requires confidence decisions to combine the agent's self-assessed ability, task complexity, guardrail strength, rollback or repair paths, and whether strong tests or benchmarks can safely drive broken optimizations back to green.
-- Reduces avoidable repeated computation, unnecessary serialization/parsing, allocation churn, IO round trips, inefficient query patterns, and unbounded concurrency.
-- Introduces caching or memoization only when ownership, invalidation, size bounds, and failure behavior are clear.
-- Treats large coupled hot paths as staged unlock problems, not as automatic stop signals.
-- Re-scans the full repository after every iteration and repeats while any known in-scope actionable performance issue or unvisited in-scope module remains.
-- Synchronizes project docs and `AGENTS.md/CLAUDE.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
-
-## Repository structure
-
-- `SKILL.md`: Main three-step loop, dependencies, guardrails, and output contract.
-- `agents/openai.yaml`: Agent interface metadata and default prompt.
-- `references/`: Focused guides for scanning, module coverage, job selection, measurement, algorithmic complexity, IO, caching, hot loops, concurrency, unlock work, and iteration gates.
-
-## Typical usage
-
-```text
-Use $iterative-code-performance to improve this repository's speed end to end without changing business behavior or macro architecture.
-```
-
-## License
-
-MIT. See `LICENSE`.

package/iterative-code-performance/SKILL.md

@@ -1,116 +0,0 @@
----
-name: iterative-code-performance
-description: >-
-  Improve an existing codebase through repeated evidence-based repository-wide
-  performance scans, module-by-module deep-read coverage, and behavior-safe
-  speed optimizations until no known in-scope actionable bottleneck or unvisited
-  in-scope module remains: measure hot paths, reduce algorithmic complexity,
-  remove avoidable repeated work, optimize IO and batching, control allocation
-  churn, improve caching only where invalidation is clear, and add benchmark or
-  regression guardrails while preserving intended business behavior and the
-  system's macro architecture. Use when users ask for comprehensive speed,
-  latency, throughput, CPU, memory-allocation, query, batching, or hot-path
-  optimization across a repository.
----
-
-# Iterative Code Performance
-
-## Dependencies
-
-- Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
-- Conditional: `systematic-debug` when a performance test, benchmark, load run, or production trace exposes a real business-logic defect that must be fixed at the true owner; `improve-observability` when profiling signals are missing or measurement requires durable logs, metrics, or traces.
-- Optional: `improve-observability` for profiling signals or durable metrics needed during optimization.
-- Fallback: If required completion dependencies are unavailable, finish performance work and validation first, then report exactly which documentation, constraint-sync, or observability action could not run.
-
-## Standards
-
-- Evidence: Read repository docs, project constraints, source, tests, logs, benchmarks, profiler output, build scripts, entrypoints, and nearby abstractions before editing; every optimization must be justified by measured evidence or clear complexity analysis tied to a plausible hot path.
-- Execution: Run a continuous three-step loop of full-codebase performance scan → choose this round's jobs and optimize → if and only if the latest full-codebase scan is clear, update docs and constraints; otherwise return to scanning immediately. Maintain a module inventory and coverage ledger so every in-scope module receives a performance-oriented deep-read iteration before completion. Do not treat jobs as workflow steps. Do not produce a completion report while any known in-scope actionable bottleneck or unvisited in-scope module remains.
-- Quality: Resolve as many inherited performance problems as safely possible without changing intended behavior or the system's macro architecture. Do not optimize by guessing, weakening correctness, adding stale caches, hiding failures, or moving cost to another critical path without evidence.
-- Output: Return iteration-by-iteration decisions, selected jobs, module coverage status, changed files, speedup or complexity evidence, behavior-preservation evidence, benchmark and regression guardrails, validation results, and docs/constraint sync status only after the latest scan shows no remaining known actionable in-scope bottleneck and no unvisited in-scope module.
-
-## Mission
-
-Leave the repository materially faster by continuously scanning the whole codebase, landing the highest-value safe performance optimizations available at each moment, and repeating until there is no known in-scope actionable performance gap left to fix.
-
-For this skill, `macro architecture` means the system's top-level runtime shape and overall operating logic: major subsystems, top-level execution model, deployment/runtime boundaries, persistence model, service boundaries, and the end-to-end way the whole system works. Ordinary module interactions, helper extraction, local data-structure changes, internal batching, query shaping, memoization inside an owner, and local hot-path decomposition do not count as macro-architecture changes by themselves.
-
-## Three-Step Loop
-
-### 1) Scan the repository
-
-- Read root guidance first: `AGENTS.md/CLAUDE.md`, `README*`, package manifests, task runners, CI/test config, benchmark tooling, profiler setup, and major project docs.
-- Map runtime entrypoints, domain modules, external integrations, persistence/query boundaries, queue or job workers, request paths, hot loops, and current performance guardrails.
-- Exclude generated, vendored, lock, build-output, fixture, snapshot, or minified files unless evidence shows they are human-maintained source.
-- Build or refresh a concrete repository-wide backlog of known actionable performance issues.
-- Build or refresh a module inventory and coverage ledger; every in-scope module starts as unvisited until it has received a performance-oriented deep-read iteration with callers, callees, tests, logs, benchmarks, relevant contracts, and each available job lens inspected.
-- Re-scan the full codebase after every landed iteration, not only the files just changed.
-- Load `references/repository-scan.md` for the scan checklist and performance-backlog shaping rules.
-- Load `references/module-coverage.md` for module inventory, performance deep-read coverage, easy-first ordering, and completion rules.
-
-### 2) Choose this round's jobs and optimize
-
-- Choose jobs only after the latest full-codebase performance scan. Jobs are optional execution directions, not ordered workflow steps.
-- Treat module scanning and job choice as one linked activity: inspect the selected module through every available performance job lens before deciding which jobs actually land in this round.
-- Select the smallest set of jobs that can safely improve the currently selected module or module cluster under current correctness and measurement guardrails.
-- Before choosing or deferring an optimization, explicitly assess implementation confidence as a combination of the agent's own ability to understand and complete the change, the objective safety net from tests, benchmarks, and other guardrails, the clarity of rollback or repair paths, and the task's inherent difficulty. Do not treat difficulty alone as low confidence; when strong tests and benchmarks guard the behavior, use them to support bolder changes because failures can be driven back to green.
-- Prefer evidence-first ordering: start with bottlenecks that are measured, user-visible, high-frequency, or have clear algorithmic waste; use easy-first module ordering when it builds profiling context, tests, benchmarks, or seams that make harder hot paths safer later.
-- Do not keep revisiting familiar modules while other in-scope modules remain unvisited unless the familiar module blocks the next unvisited module's safe performance deep read.
-- Prefer smaller, high-confidence optimizations that reduce latency, CPU, memory churn, IO round trips, or repeated work without broad behavior risk.
-- If a desired optimization is high-risk and weakly guarded, make benchmark, characterization, or regression guardrail-building part of this round instead of stopping.
-- If a file feels too coupled, too central, or too risky for a direct hot-path rewrite, do staged unlock work rather than declaring the area blocked.
-- Read all directly affected callers, tests, interfaces, logs, persistence/query contracts, cache invalidation rules, and concurrency assumptions before editing.
-- Validate from narrow to broad after each bounded round, then perform a full-codebase stage-gate decision:
-  - if any known in-scope actionable bottleneck still remains or any in-scope module has not received a deep-read iteration, return to Step 1;
-  - only continue to Step 3 when the latest scan is clear.
-
-Load references for this step only as needed:
-
-- `references/module-coverage.md` for choosing the next module and proving every in-scope module has been deeply read through the available performance-job lenses.
-- `references/job-selection.md` for next-job choice conditions and tie-breakers.
-- `references/measurement-and-benchmarking.md` for profiling, benchmark, baseline, and before/after comparison rules.
-- `references/algorithmic-complexity.md` for complexity, data-structure, and repeated-work optimization.
-- `references/io-batching-and-queries.md` for database, network, filesystem, external API, and batching optimization.
-- `references/caching-and-memoization.md` for safe cache introduction, cache removal, and invalidation rules.
-- `references/allocation-and-hot-loops.md` for CPU loops, allocation churn, serialization, parsing, and memory-pressure cleanup.
-- `references/concurrency-and-pipelines.md` for bounded parallelism, async pipelines, backpressure, and queue throughput.
-- `references/coupled-hot-path-strategy.md` for staged unlock work on large coupled or apparently core hot-path files.
-- `references/iteration-gates.md` for validation cadence, stage-gate rules, and stop criteria.
-
-### 3) Update project documents and constraints
-
-Only enter this step when the latest full-codebase scan confirms there is no remaining known actionable in-scope performance issue and every in-scope module has received a deep-read iteration, except items explicitly classified as blocked, unsafe, speculative, low-value, excluded, approval-dependent, or requiring production-only measurement that is unavailable.
-
-- Run `align-project-documents` when README, architecture notes, setup docs, benchmark docs, performance budgets, operational docs, or test guidance may have drifted.
-- Run `maintain-project-constraints` to verify `AGENTS.md/CLAUDE.md` still matches the repository's real architecture, business flow, commands, and conventions.
-- Update only the documentation and constraints that changed in reality because of the optimization.
-
-## Hard Guardrails
-
-- Do not change intended business logic while optimizing, except to fix a real defect exposed by tests and verified at the true owner.
-- Do not change the system's macro architecture unless the user explicitly expands scope.
-- Do not optimize from vibes alone; require measurement, traces, logs, benchmark baselines, complexity analysis, or repeatable workload evidence.
-- Do not add caches without explicit ownership, invalidation, size bounds, failure behavior, and tests or equivalent validation.
-- Do not improve one metric by silently worsening a more important user-visible path, correctness invariant, memory ceiling, or operator workflow.
-- Do not use one-off scripts to rewrite product code.
-- Do not stop early just because a hot path is large, central, or historically fragile; if a safe unlock step exists, that is the next job.
-- Do not stop before every in-scope module has been inventoried, deeply read, and either improved, validated as clear, or explicitly deferred/excluded with evidence.
-- Do not weaken tests, benchmarks, timeouts, or assertions to make an optimization pass; fix the real defect, stabilize the benchmark, or update stale expectations to stable invariants.
-- Do not add micro-optimizations that make code harder to maintain unless evidence shows the path is hot enough to justify the tradeoff.
-
-## Completion Report
-
-Only report completion after Step 3 is done, the latest Step 1 scan is clear, and the module coverage ledger has no unvisited in-scope module.
-
-Return:
-
-1. Iterations completed and the jobs selected in each iteration.
-2. Stage-gate verdict after each full-codebase re-scan.
-3. Module coverage ledger summary: modules deep-read, improved, validated-clear, deferred, or excluded.
-4. Key files changed and the performance issue each change resolved.
-5. Speedup evidence, complexity change, or bottleneck-removal evidence, including baseline and after measurements where available.
-6. Business behavior preservation evidence.
-7. Benchmarks, regression tests, or other guardrails added or updated, including property/integration/E2E/load-test `N/A` reasons where relevant.
-8. Validation commands and results.
-9. Documentation and `AGENTS.md/CLAUDE.md` synchronization status.
-10. Remaining blocked, production-measurement-only, or approval-dependent items, if any.

package/iterative-code-performance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Iterative Code Performance"
-  short_description: "Optimize latency, throughput, CPU, IO, caching, and hot paths in repeated safe passes"
-  default_prompt: "Use $iterative-code-performance as a strict three-step loop. Step 1: scan the full repository for performance evidence, refresh the actionable bottleneck backlog, and maintain a module inventory plus performance coverage ledger. Step 2: choose this round's module or bounded module cluster, scan it through every available performance job lens, and only then decide which jobs actually land now; prioritize measured or clearly complexity-backed hot paths, jobs are selectable directions rather than workflow steps, and assess optimization confidence from your own ability to understand and complete the change, task complexity, guardrail strength, rollback or repair paths, and whether tests or benchmarks can drive accidental breakage back to green. If a high-risk hot path is weakly guarded add benchmarks, characterization tests, or other guardrails instead of stopping; if strong tests and benchmarks guard the behavior, use them to justify bolder safe optimizations rather than avoiding the work. If a file is too coupled or too central for direct optimization, switch to staged unlock work and keep progressing. After validation, run a full-codebase stage-gate; if any known in-scope actionable bottleneck remains or any in-scope module has not received a performance-oriented deep-read iteration, go back to Step 1 immediately. Step 3: only when the latest full-codebase performance scan is clear and every in-scope module is deeply read through the available-job lenses, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md/CLAUDE.md. Preserve intended business behavior and the system's macro architecture, keep correctness guardrails green, and do not write a completion report while actionable bottlenecks or unvisited modules still exist."

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.