# Code Optimization > Lifecycle perf audit Go/Rust/TS/Python. N+1/leak/duplication sweeps, tri-axis Impact×Risk×Effort, writes OPTIMIZATION_REPORT.md. Read-only — file:line evidence. Triggers: 'optimize code', 'otimizar código', 'auditar performance', 'find bottlenecks', '/code-optimization'. - **Type:** Skill - **Install:** `agentstack add skill-bruno-cunha-souza-valarmindskills-code-optimization` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Bruno-Cunha-Souza](https://agentstack.voostack.com/s/bruno-cunha-souza) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Bruno-Cunha-Souza](https://github.com/Bruno-Cunha-Souza) - **Source:** https://github.com/Bruno-Cunha-Souza/ValarMindSkills/tree/main/skills/code-optimization ## Install ```sh agentstack add skill-bruno-cunha-souza-valarmindskills-code-optimization ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Code Optimization Lifecycle > "Premature optimization is the root of all evil. Yet that does not mean we should ignore opportunities for optimization." — Donald Knuth This skill conducts a structured, evidence-first **performance and efficiency** audit. It is **read-only on source code** — it never edits production code, but it writes a single report file (`OPTIMIZATION_REPORT.md`) at the project root. It is **language-aware** for Go (Gin/Fiber/fx), Rust (Axum/Actix/Tokio), TypeScript (Node/Bun/Elysia/Fastify), and Python (FastAPI/Django/Flask, CPython 3.13 / 3.14 including free-threaded 3.14t). It is **lifecycle-driven**: detect → triage → sweep → read → validate → classify → report. The skill exists because **performance findings are the most prone to hallucination**: invented latency numbers, guessed bottlenecks, untested allocation claims. Every constraint pushes the reviewer to cite file:line, quote tool output, and grade Impact / Risk / Effort separately so the user can prioritize without re-reading the entire diff. This skill is the perf-focus sibling to `@code-review` (broad), `@code-security-review` (security-focus), and `@code-debugger` (runtime). Coexists with them. ## When to Use - **Latency regression** detected in staging / production — find the cause, prioritize the fix. - **Cost reduction** — cloud bill driven by CPU, memory, or DB calls; find waste. - **Pre-release perf gate** — confirm the build matches the SLO targets before tagging. - **Post-incident sweep** — after an OOM, connection pool exhaustion, or thundering herd, audit related code for similar latent issues. - **Refactor planning** — quantify perf debt before deciding scope. - **Greenfield review** — ensure the new module does not bake in N+1, blocking I/O, or unbounded growth. - The user explicitly asks: `'optimize code'`, `'otimizar código'`, `'performance review'`, `'auditar performance'`, `'find bottlenecks'`, `'analisar gargalos'`, or invokes `/valarmindskills:code-optimization`. ## Do not use when - The user wants to **fix correctness bugs** (panic, wrong output, race that corrupts state) — use `@code-debugger`. - The user wants a **security audit** — use `@code-security-review`. A perf finding that overlaps security (e.g., DoS via unbounded query) is reported here AND cross-linked to `@code-security-review`. - The user wants a **generic PR review** covering correctness + style + security — use `@code-review` (perf appears in Phase 4 there, but shallow). - The user wants pure **refactoring for readability** without perf motivation — use `@clean-code`. - The diff is a single typo, comment edit, or trivial rename — overhead exceeds value; tell the user and stop. - The project is in a language the skill does not cover (not Go, Rust, TypeScript, or Python). Surface the gap and ask whether the user wants a generic principles-only pass. ## Prerequisites Each tool's absence is logged and the related Phase degrades but is never silently skipped. Default mode is **static perf review**: read sources, run linters, run language profilers when the user authorizes. Live benchmarking and load testing are **optional verification**, not part of the default review. | Tool | Language | Purpose | | --- | --- | --- | | `git`, `gh`, `rg`, `fd` | all | Diff inspection, pattern sweep, file finder | | `jscpd` | all | Multi-language clone detection (duplication audit) | | `go test -bench` + `pprof` (`go tool pprof`) | Go | CPU / alloc / goroutine / mutex / block profiling | | `go build -gcflags='-m'` | Go | Escape analysis | | `dupl` | Go | Go-specific duplication | | `cargo flamegraph` + `criterion` + `cargo bloat` | Rust | CPU flamegraph, micro-benchmark, binary size attribution | | `cargo-machete` + `cargo-udeps` | Rust | Unused deps | | `clinic.js` (`doctor`/`flame`/`bubbleprof`/`heapprofile`) | Node | Event-loop, CPU flame, async, heap | | `bun --hot` + `Bun.nanoseconds()` | Bun | Native micro-bench | | `knip` | TS | Unused exports / files / deps | | `cProfile` + `py-spy` + `line_profiler` + `tracemalloc` + `pytest-memray` | Python | CPU sampling, line-level, alloc tracing | | `pytest --benchmark` (`pytest-benchmark`) | Python | Micro-bench | | `WebSearch` + context7 MCP (Claude Code: `mcp__context7__resolve-library-id` + `mcp__context7__query-docs`; Cursor: `CallMcpTool` on server `user-context7` with `resolve-library-id` / `query-docs`) | all | Phase 4 conditional validation. If context7 is not configured on the host, Phase 4 falls back to WebSearch only — document the gap in the report's `external validation:` field. | Required access: - [ ] Read access to the repo and the diff - [ ] Permission to invoke linters, profilers, and dependency scanners on the host - [ ] **Permission to write `OPTIMIZATION_REPORT.md` at project root** — this is the only write this skill performs - [ ] Explicit user request before running live benchmarks or load tests The skill does **not** require write access to source files. It never commits, never pushes, never edits source code. ## Phase 0 — Project & Documentation Detection Detect language, framework, package manager. Read project docs (README, ARCHITECTURE, ADR, CONTRIBUTING) **before** any sweep — assumptions about hot paths or perf targets without docs lead to inflated findings. ```bash # Step 1 — language at the repo root test -f go.mod && echo "language: go" test -f Cargo.toml && echo "language: rust" test -f package.json && echo "language: typescript" { test -f pyproject.toml || test -f requirements.txt || test -f setup.py; } && echo "language: python" # Step 2 — framework (single most authoritative match wins) case "$LANG" in go) rg -q 'gin-gonic/gin' go.mod && echo "framework: gin" rg -q 'gofiber/fiber/v[23]' go.mod && echo "framework: fiber" rg -q 'go.uber.org/fx' go.mod && echo "framework: fx (DI)" ;; rust) rg -q '\baxum\b' Cargo.toml && echo "framework: axum" rg -q '\bactix-web\b' Cargo.toml && echo "framework: actix" rg -q '\brocket\b' Cargo.toml && echo "framework: rocket" ;; typescript) test -f bun.lockb && echo "runtime: bun" test -f package-lock.json && echo "runtime: node, pm: npm" test -f pnpm-lock.yaml && echo "runtime: node, pm: pnpm" rg -q '"elysia"' package.json && echo "framework: elysia" rg -q '"fastify"' package.json && echo "framework: fastify" rg -q '"express"' package.json && echo "framework: express" rg -q '"hono"' package.json && echo "framework: hono" ;; python) test -f uv.lock && echo "pm: uv" test -f poetry.lock && echo "pm: poetry" test -f Pipfile.lock && echo "pm: pipenv" rg -q '(^|[[:space:]"])fastapi[>=/dev/null && echo "framework: fastapi" rg -q '(^|[[:space:]"])django[>=/dev/null && echo "framework: django" rg -q '(^|[[:space:]"])flask[>=/dev/null && echo "framework: flask" ;; esac # Step 3 — project documentation (read before sweeping) fd -t f -i -d 3 '(README|ARCHITECTURE|ADR|CONTRIBUTING|PERFORMANCE|BENCHMARKS)' . ``` Persist as `$LANG ∈ {go, rust, typescript, python}`, `$FRAMEWORK`, `$PM`, `$RUNTIME` (TS only). | `$LANG` | Reference to load | Primary profiler | | --- | --- | --- | | `go` | [references/GOLANG.md](references/GOLANG.md) | `go test -bench` + `pprof` | | `rust` | [references/RUST.md](references/RUST.md) | `cargo flamegraph` + `criterion` | | `typescript` | [references/TYPESCRIPT.md](references/TYPESCRIPT.md) | `clinic.js` (Node) / `Bun.nanoseconds()` (Bun) | | `python` | [references/PYTHON.md](references/PYTHON.md) | `py-spy` + `cProfile` + `tracemalloc` | Cross-cutting refs are always loaded: - [references/DUPLICATION.md](references/DUPLICATION.md) — DRY violations, duplicate detection (jscpd, dupl, cargo-duplicates, eslint-plugin-sonarjs), Rule of Three. - [references/RESOURCES.md](references/RESOURCES.md) — memory leaks, CPU-bound, file/socket leaks, goroutine/task leaks, connection pool exhaustion. - [references/CALLS.md](references/CALLS.md) — N+1, async batching, caching strategies, dataloader, HTTP keep-alive, serialization hot paths. If no documentation exists, infer conventions from `git log --oneline -20`, top-level directory layout, and CI config. Document the inference in the Phase 6 report under `assumptions:`. ## Phase 1 — Scope & Module Triage Count files and lines of code in the target. Large projects must be sliced into modules before review — sweeping a 50k-LOC monolith dilutes attention and amplifies hallucination risk. ```bash fd -t f -e go -e rs -e ts -e tsx -e py -d 10 . | wc -l # total source files fd -t f -e go -e rs -e ts -e tsx -e py -d 10 -x wc -l {} + | tail -1 # total LOC # Module candidates fd -t d -d 3 '^(cmd|internal|pkg|src|api|app|services?|core|domain)$' . ``` | Project size | Action | | --- | --- | | ≤ 100 files **and** ≤ 20k LOC | Sweep the whole project in one pass | | > 100 files **or** > 20k LOC | List discovered modules, propose top 3–5 candidates (the ones changed most recently per `git log` OR named in `--scope` arg), ask user to confirm scope before continuing | | > 500 files **or** > 100k LOC | Refuse a full sweep — require explicit module list | Stop the phase here and confirm with the user when triage is required. ## Phase 2 — Static & Profile Sweep Run the static perf-aware toolchain. Treat results as **leads**, never as conclusions. Calibration: every automated finding starts at **Medium** Impact; promotion to High / Critical requires manual evidence in Phase 3 (a quoted code path) or Phase 4 (external validation). ```bash # Polyglot duplication (always) jscpd --min-lines 5 --min-tokens 50 . # Go — static (always; no consent needed) go build -gcflags='-m=2' ./... # escape analysis → heap allocations go vet ./... golangci-lint run ./... staticcheck ./... dupl -t 50 ./... # Optional with user consent (live profiling — may be slow on monorepos): # go test -bench=. -benchmem -cpuprofile=/tmp/cpu.pprof -memprofile=/tmp/mem.pprof ./... # go tool pprof -top -cum /tmp/cpu.pprof | head -30 # Rust cargo build --release --timings # compile-time + dep graph cargo clippy --all-targets -- -D warnings -W clippy::pedantic cargo bloat --release --crates -n 30 # binary attribution cargo machete # unused deps # Optional with user consent: cargo flamegraph -- # TypeScript / Node / Bun bunx tsc --noEmit bunx knip # Optional: clinic doctor -- node dist/server.js (interactive, user runs) # Python ruff check . --select=PERF,SIM,B,C90 # PERF rules + complexity (ruff) mypy --strict . # type info catches inefficient typing # Optional with user consent: py-spy record -d 30 -o /tmp/profile.svg -- python -m # Optional: pytest --benchmark-only --benchmark-save=baseline ``` Capture every tool's version (` --version`) and embed it in the report under `tools:`. A finding without a tool version is not reproducible. ## Phase 3 — Manual Read + Pattern Sweep Read the targeted modules with perf eyes. The automated tools see syntax; only the reader sees intent. ### 3.1 Read order 1. **Hot path entry points** — request handlers, controllers, queue consumers. 2. **DB layer** — repositories, ORM queries, raw SQL. 3. **Loop-heavy logic** — batch jobs, transforms, serializers. 4. **External I/O** — HTTP clients, message brokers, cache clients. 5. **Concurrency primitives** — goroutines/tasks/threads/Promises, locks, channels. ### 3.2 Per-category sweeps For each, run the per-language grep (`$LANG` reference file has the exact commands) plus the cross-cutting reference: | Category | Cross-cutting ref | Per-language ref | | --- | --- | --- | | Duplication | [DUPLICATION.md](references/DUPLICATION.md) | language refs §Duplication | | Resource leaks (memory, FD, goroutine, task, connection pool) | [RESOURCES.md](references/RESOURCES.md) | language refs §Resources | | Call efficiency (N+1, batching, caching, serialization) | [CALLS.md](references/CALLS.md) | language refs §Calls | | Language-specific hot-path antipatterns | — | language refs §Hot Path | Every finding must include: `file:line`, a quoted code block (verbatim from the file), the anti-pattern category, the suggested change, and a draft tri-axis grade (Impact / Risk / Effort). Findings without all five fields are dropped at Phase 5. ### 3.3 Read-through questions For each hot path read, answer: - What does this code take in the **worst case** — time, memory, allocations? Quote the structures it iterates. - Where does an **unbounded** input come from? (request body, DB row count, file size, message size) - Could this be **batched** instead of done in a loop? - Could this be **cached** safely? What is the cache key, TTL, invalidation? - What resource is acquired? Is it released on the **error path** as well as the success path? - Could this **block** the event loop / goroutine pool / async runtime? - What is the **serialization cost** of the response? Is the dataset bounded? A finding is born only when the answer reveals a concrete cost AND the evidence is in the code. Hallucinations are findings born without both. ## Phase 4 — External Validation (conditional) **Trigger:** any draft finding with `Impact >= High AND Confidence `). Findings that fail validation are either dropped or rewritten as `Info` observations. This phase is **opt-out by default per-finding** — skip when the user passed `--no-validate` or when every High/Critical draft already has High confidence from Phase 3 evidence. ## Phase 5 — Classification & Synthesis Grade every surviving finding on three axes per [references/SEVERITY_RUBRIC.md](references/SEVERITY_RUBRIC.md). ### 5.1 Tri-axis matrix | Axis | Values | Calibrator | | --- | --- | --- | | **Impact** | Critical / High / Medium / Low | Latency delta (ms), throughput, cost ($/mo), memory delta (MB) — quote the units | | **Risk** | SAFE / REVIEW / BREAKING | Same definition as `@code-review`: SAFE = no observable change, REVIEW = touches boundary or shared util, BREAKING = signature/schema/response changes | | **Effort** | S ( 1 day) | Lines to touch + tests to write + surface affected | ### 5.2 Priority quadrants - **Quick wins** — `Impact ∈ {Critical, High}` AND `Effort = S`. Top of the report. - **Strategic** — `Impact ∈ {Critical, High}` AND `Effort ∈ {M, L}`. Plan and schedule. - **Polish** — `Impact ∈ {Medium, Low}` AND `Effort = S`. Tackle opportunistically. - **Defer / drop** — `Impact = Low` AND `Effort = L`. Drop from the report unless the user explicitly asked to include them. ### 5.3 Confidence tag - **High** — evidence cited, validation passed (or Phase 4 not required), pattern is well-documented. - **Medium** — pattern matches but intent could justify it; or validation was skipped. - **Low** — needs a second opinion; escalate explicitly when `Confidence = Low AND Impact >= High`. ## Phase 6 — Report Write Write a single file `OPTIMIZATION_REPORT.md` at the project root via the `Write` tool. Format per [references/REPORT_TEMPLATE.md](references/REPORT_TEMPLATE.md). The file is overwritten on every run (the user versions it via git). After writing, **print to the terminal** the summary block defined in [Output format](#output-format) so the user can decide whether to open the file. If `OPTIMIZATION_REPORT.md` already exists and the user has not confirmed overwrite, ask before overwriting. Default to overwrite when the user invoked the skill explicitly. ## Constraints - **Never edit source code.** This skill writes exactly one file: `OPTIMIZATION_REPORT.md` at the project root. Source files are read-only. - **Never invent findings to fill the report.** Zero findings is a valid outcom … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Bruno-Cunha-Souza](https://github.com/Bruno-Cunha-Souza) - **Source:** [Bruno-Cunha-Souza/ValarMindSkills](https://github.com/Bruno-Cunha-Souza/ValarMindSkills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-bruno-cunha-souza-valarmindskills-code-optimization - Seller: https://agentstack.voostack.com/s/bruno-cunha-souza - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.