Bruno-Cunha-Souza/ValarMindSkills / skills/code-optimization
code-optimization
VerifiedLifecycle 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'.
| File | Kind | Size |
|---|---|---|
| EXAMPLE.md | markdown | 10.6 KB |
| SKILL.md | skill md | 22.6 KB |
| references/CALLS.md | markdown | 9.2 KB |
| references/CHECKLIST.md | markdown | 3.6 KB |
| references/DUPLICATION.md | markdown | 5.6 KB |
| references/GOLANG.md | markdown | 7.3 KB |
| references/PYTHON.md | markdown | 9.2 KB |
| references/REPORT_TEMPLATE.md | markdown | 10.1 KB |
| references/RESOURCES.md | markdown | 6.8 KB |
| references/RUST.md | markdown | 7.6 KB |
| references/SEVERITY_RUBRIC.md | markdown | 6.5 KB |
| references/TYPESCRIPT.md | markdown | 8.0 KB |
references/REPORT_TEMPLATE.md
View on GitHub> Reference companion for the [code-optimization](../SKILL.md) skill.
# Report Template — `OPTIMIZATION_REPORT.md`
This is the exact schema for the file the skill writes at the project root in Phase 6. The file is **overwritten** on each run.
Every section is required even when empty (use `(none)` or `0`). Skipping a section makes the report not parseable by downstream tooling (CI, dashboards).
## 1. Skeleton
```markdown
# Optimization Report — <project name>
> Generated by `@code-optimization` on <YYYY-MM-DD> against `<branch>` @ `<sha[0:7]>`.
> Skill version: <git rev of SKILL.md>
## Summary
| Axis | Critical | High | Medium | Low |
| ----------- | -------- | ---- | ------ | --- |
| Count | 0 | 2 | 5 | 3 |
**Quadrant counts:**
- Quick wins (High/Critical Impact × Small Effort): 2
- Strategic (High/Critical Impact × M/L Effort): 1
- Polish (Med/Low Impact × Small Effort): 5
- Deferred (in scope but low priority): 2
**Findings dropped (Low Impact × Large Effort):** 4
## Context
- **Language(s):** python (3.13)
- **Framework:** fastapi 0.115
- **Runtime:** cpython3.13
- **Package manager:** uv
- **Scope:** 47 files / 8420 LOC (modules: `api/`, `services/`, `tasks/`)
- **Base ref:** main @ a1b2c3d
- **Tools:** ruff 0.7.4, mypy 1.13, py-spy 0.3.14, jscpd 4.0.5
- **External validation:** 2 findings cross-validated via WebSearch + context7
- **Assumptions:** no PERFORMANCE.md found; inferred SLO p99 < 200ms from `monitoring/dashboards/api-latency.json`
## Findings
### Quick Wins (priority — address before next release)
#### O001 — N+1 query in `GET /users` endpoint
| Axis | Value |
| ---------- | ---------------------------------------------------------- |
| **Impact** | High — adds 50ms p99 per request, 10× DB load |
| **Risk** | SAFE — same response shape |
| **Effort** | S (< 1h) |
| **Confidence** | High |
**File:** `api/users.py:42`
**Code (verbatim):**
\`\`\`python
@router.get("/users")
def list_users(db: Session = Depends(get_db)):
users = db.query(User).all()
return [{"id": u.id, "profile_name": u.profile.name} for u in users]
\`\`\`
**Why this is High Impact:**
- The list comprehension touches `u.profile` for each user, triggering a separate `SELECT * FROM profiles WHERE user_id=?` per row.
- With 200 users in the test DB, this is 201 queries instead of 2 (~50ms p99 measured in the team's own perf dashboard, captured in `monitoring/dashboards/api-latency.json`).
**Suggested fix (SAFE):**
\`\`\`python
@router.get("/users")
def list_users(db: Session = Depends(get_db)):
users = db.query(User).options(selectinload(User.profile)).all()
return [{"id": u.id, "profile_name": u.profile.name} for u in users]
\`\`\`
**Validation:**
- context7 `/sqlalchemy/sqlalchemy` §loading.html — `selectinload` is documented as the antidote to N+1 with one-to-many relationships.
**Verification:**
- Add a pytest assertion using `event.listen(Engine, "before_cursor_execute", counter)` to assert ≤ 2 queries.
**Cross-link:** none.
---
#### O002 — `json` module on hot response path (15% CPU)
| Axis | Value |
| ---------- | ---------------------------------------------------------- |
| **Impact** | High — measured 15% CPU on `api/orders` under `wrk` load |
| **Risk** | REVIEW — middleware change, affects all JSON responses |
| **Effort** | S (< 1h) |
| **Confidence** | High |
**File:** `api/main.py:18`
**Code (verbatim):**
\`\`\`python
app = FastAPI() # default JSONResponse uses stdlib `json`
\`\`\`
**Why this is High Impact:**
- py-spy flamegraph (`/tmp/profile.svg` from Phase 2) shows 18% of CPU time in `json.dumps`.
- `orjson` is 2–3× faster on dict-heavy payloads and emits identical output for the response shapes here.
**Suggested fix (REVIEW):**
\`\`\`python
from fastapi.responses import ORJSONResponse
app = FastAPI(default_response_class=ORJSONResponse)
\`\`\`
**Validation:**
- WebSearch: https://fastapi.tiangolo.com/advanced/custom-response/#orjsonresponse — official recommendation for high-throughput APIs.
**Verification:**
- Re-run py-spy load test and confirm `json.dumps` falls below 5% in flamegraph.
- Diff response bodies on a sample of endpoints to confirm byte-identical for the schemas in use.
---
### Strategic (schedule for upcoming sprint)
#### O003 — `GET /orders` returns full table without pagination
| Axis | Value |
| ---------- | ---------------------------------------------------------- |
| **Impact** | Critical — OOM observed in staging when user has >50k orders |
| **Risk** | BREAKING — response shape changes (adds `next_cursor`) |
| **Effort** | M (1–8h) |
| **Confidence** | High |
**File:** `api/orders.py:67`
**Code (verbatim):**
\`\`\`python
@router.get("/orders")
def list_orders(user_id: int, db: Session = Depends(get_db)):
return db.query(Order).filter(Order.user_id == user_id).all()
\`\`\`
**Why this is Critical:**
- Staging incident `INC-2024-08-14` (referenced in `docs/incidents/`) shows a user with 67k orders OOMed the worker.
- Marshalling 67k rows into JSON also blows the response timeout.
**Suggested fix (BREAKING):**
- Add cursor pagination with default page size 100, max 500.
- Migration path: dual-version the endpoint as `/v2/orders` with pagination; deprecate `/orders` with a warning header for 1 release.
**Verification:**
- Load test with 100k-order user, assert p99 < 200ms and constant memory.
- Backfill API consumers (search via gh) to confirm migration path.
**Cross-link:** `@code-security-review` — same finding doubles as DoS surface (API4 Unrestricted Resource Consumption).
---
### Polish (opportunistic)
#### O004 — `string +=` accumulation in CSV export
| Axis | Value |
| ---------- | ---------------------------------------------------------- |
| **Impact** | Medium — O(N²) growth on export |
| **Risk** | SAFE |
| **Effort** | S (< 30min) |
| **Confidence** | High |
**File:** `services/export.py:88`
**Code (verbatim):**
\`\`\`python
csv = ""
for row in rows:
csv += ",".join(row) + "\n"
\`\`\`
**Suggested fix (SAFE):**
\`\`\`python
csv = "\n".join(",".join(row) for row in rows)
\`\`\`
**Validation:** none required — well-known antipattern.
---
### Deferred / Dropped
| ID | Title | Reason |
| -- | ----- | ------ |
| O005 | Replace ORM with raw SQL in `services/reporting.py` | Effort=L, Impact=Medium → DEFER. Re-evaluate if reporting becomes a hot path. |
| — | (4 Low/Large findings dropped from report — visible in skill stdout) | |
## Methodology
- **Phase 0 — Detection:** language python, framework fastapi 0.115, pm uv.
- **Phase 1 — Triage:** 47 files / 8420 LOC ≤ 100/20k threshold → full sweep.
- **Phase 2 — Static sweep:** ruff PERF rules clean; py-spy 30s sample during `wrk` load; jscpd showed 2 minor clones (graded Low).
- **Phase 3 — Manual read:** request handlers + ORM + serializers.
- **Phase 4 — External validation:** 2 findings cross-validated (O001, O002).
- **Phase 5 — Classification:** quadrants assigned per `references/SEVERITY_RUBRIC.md`.
- **Phase 6 — Report:** this file.
## Next steps
1. Address Quick Wins (O001, O002) — total estimated effort: ~1.5h.
2. Open ticket for Strategic finding (O003) with migration plan; aim for next sprint.
3. Re-run `/code-optimization` after fixes to confirm Impact resolution.
```
## 2. Schema rules
- **One H3 per finding.** Format: `#### <ID> — <title>` (Quick Wins / Strategic / Polish) or row in table (Deferred / Dropped).
- **ID format:** `O<NNN>` zero-padded. Auto-increment within a single run; restart at `O001` per run (no cross-run persistence).
- **Code blocks must quote verbatim** with the file name and line range hinted, but the content matches the file at the cited line byte-for-byte.
- **Validation field is required for `Impact >= High AND Confidence < High`** unless `--no-validate` was set; otherwise it may say `Validation: not required`.
- **Cross-link line is required** when the finding overlaps another skill's domain (security, debugging, refactor mechanics, CI gate).
- **Mermaid diagrams are not used.** Tables only. The report is meant to be read in any markdown renderer + on GitHub PR diffs.
## 3. Anti-patterns to avoid in the report
- **Inventing latency numbers** without a profile or doc citation.
- **Mixing fix risk with bug risk** in the Risk axis.
- **Inflating Effort** to make a Quick Win look Strategic (or vice-versa).
- **Padding** with "consider X" findings that have no code citation.
- **Duplicating findings** across quadrants — assign each finding to exactly one quadrant.
## 4. LGTM variant
When the run produces zero findings:
```markdown
# Optimization Report — <project name>
> Generated by `@code-optimization` on <YYYY-MM-DD> against `<branch>` @ `<sha[0:7]>`.
## Summary
LGTM — no perf issues found in scope.
| Axis | Critical | High | Medium | Low |
| ----- | -------- | ---- | ------ | --- |
| Count | 0 | 0 | 0 | 0 |
## Context
(as above)
## Methodology
(as above — phases walked, tools versions, scope)
## Why no findings
- Hot paths inspected: `api/users.py`, `api/orders.py`, `services/export.py`.
- Static tools clean: ruff PERF, jscpd, escape-analysis output trivial.
- py-spy flamegraph shows balanced CPU distribution; no single function > 8% of samples.
## Next steps
- Run again before next release.
- Re-run with `--scope=services/` if a new bottleneck appears.
```
Info-class observations are allowed after the LGTM line **only** when grounded in files actually read in this run.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |