Skip to content

Bruno-Cunha-Souza/ValarMindSkills / skills/code-optimization

code-optimization

Verified

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'.

FileKindSize
EXAMPLE.mdmarkdown10.6 KB
SKILL.mdskill md22.6 KB
references/CALLS.mdmarkdown9.2 KB
references/CHECKLIST.mdmarkdown3.6 KB
references/DUPLICATION.mdmarkdown5.6 KB
references/GOLANG.mdmarkdown7.3 KB
references/PYTHON.mdmarkdown9.2 KB
references/REPORT_TEMPLATE.mdmarkdown10.1 KB
references/RESOURCES.mdmarkdown6.8 KB
references/RUST.mdmarkdown7.6 KB
references/SEVERITY_RUBRIC.mdmarkdown6.5 KB
references/TYPESCRIPT.mdmarkdown8.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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall