/performance-review

name: performance-review
description: Static-analysis hot-spot review for time and space complexity.

Performance Review Command

Static-analysis hot-spot review for time and space complexity.

Usage

/performance-review                  # scan changed files
/performance-review path/to/file.py  # scan one file
/performance-review --tier 1         # force Tier 1 only (skip gauntlet)

What It Does

1. **Context**: Identify target files (changed or argument-named). 2. **Tier 1: AST scan**: Detect Python time/space hotspots (nested loops, list `in` lookups, string concat, regex recompile, list-vs-generator, copy-in-loop). 3. **Tier 2: tree-sitter** (if `tree_sitter_language_pack` is installed): nested same-iterable loops, list scans in loops, and appends in nested loops for JS/TS, Go, Rust, Java, C/C++. 4. **Tier 3: gauntlet graph** (if gauntlet is installed and a `.gauntlet/graph.db` exists above the file): raise a finding one severity step when a function it calls, directly or transitively, holds a hotspot. 5. **Report**: Group findings by severity. Each finding cites `file:line`, severity, category (`time`/`space`), the pattern detected, and a concrete suggestion.

Detection Categories

| Tier | ID | Pattern | |---|---|---| | 1 | T1 | Nested `for` over the same iterable (HIGH) | | 1 | T2 | `x in <list>` inside a loop (HIGH) | | 1 | T3 | `re.compile()` inside a loop (MEDIUM) | | 1 | T4 | String `+=` accumulator in a loop (MEDIUM) | | 1 | T5 | Recursive function without `@cache` (LOW) | | 1 | T6 | List comprehension passed to a reducer (LOW) | | 1 | S1 | `.append()` inside nested loops (MEDIUM) | | 1 | S2 | `list(...)` wrapping a generator in a reducer (LOW) | | 1 | S3 | `.copy()` / `dict()` / `list()` in a loop (MEDIUM) | | 2 | * | Same patterns adapted to non-Python via tree-sitter | | 3 | * | Severity upgrades from transitive call analysis |

Manual Review Lenses

Three patterns are reviewed by eye, not by the AST scan (see `Skill(pensive:performance-review)` module `memory-allocation-lenses.md`):

• Unbounded collection fed from an external or dynamic source

(ARP table, directory scan, API page loop) with no cap.

• Hot-path recompute of derived data whose inputs change only

on infrequent events (memoize behind a generation counter).

• Serial blocking I/O in a loop over an unbounded collection

(cap the set, bound concurrency, add per-call timeouts).

Findings from these lenses must name their growth mode: persistent RSS growth versus transient per-frame churn.

When to Skip

• Code is hot-path-irrelevant (config readers, one-shot scripts).
• The "hotspot" is intentional (e.g., a data-prep step where

clarity beats micro-optimization).

• The reviewed function has runtime profiling already published.

For runtime profiling rather than static analysis, see `Skill(parseltongue:python-performance)`.

Output

A grouped findings list with file:line citations, severity, and fix suggestions. No findings means no detected patterns: not a guarantee of optimal performance.

Fallback Behavior

Install the optional extra (`uv sync --extra tiers` in `plugins/pensive`) to enable Tier 2. Tier 3 also needs the gauntlet plugin importable, which `uv sync` in `plugins/pensive` provides through the dev group. Without them:

• Tier 1 still runs (Python AST is stdlib).
• Tier 2 returns empty when `tree_sitter_language_pack` is

missing (sentinel-guarded import).

• Tier 3 returns the findings unchanged when gauntlet is missing

or no `.gauntlet/graph.db` exists above the file.

Reviews of non-Python source without the extra produce zero findings: that is correct behavior, not an error. A non-Python file that tree-sitter cannot parse adds a warning to the result. Build the graph with `python3 plugins/gauntlet/scripts/graph_build.py <root>`.

If `plugins/gauntlet/scripts/graph_build.py` is absent (a marketplace install, not a checkout), skip this step and say so.

Related Skills

• `Skill(pensive:performance-review)`: methodology this command

invokes.

• `Skill(pensive:code-refinement)`: broader refactoring guidance

including the existing `algorithm-efficiency` module.

• `Skill(parseltongue:python-performance)`: runtime profiling.