performance-review
Detects time and space complexity hotspots via AST scan. Use when code feels slow, before performance-sensitive merges, or to find O(n²) regressions.
How do I install this agent skill?
npx skills add https://github.com/athola/claude-night-market --skill performance-reviewIs this agent skill safe to install?
- Gen Agent Trust Hubpass
Performance Review is a code analysis skill that identifies complexity hotspots through static analysis of Python and other languages. It supports multiple analysis tiers, including optional call-graph integration. The skill is assessed as low risk due to the surface for indirect prompt injection when processing external source code and recommendations for third-party software installation.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Performance Review
Static-analysis review of time and space complexity hotspots.
The skill runs in three escalating tiers. Tier 1 uses Python's
stdlib ast and always runs. Tier 2 uses tree-sitter to extend
detection to JS/TS, Go, Rust, Java, and C/C++ when the tiers
extra is installed. Tier 3 walks the gauntlet call graph forward
from each finding and raises its severity one step when a callee
holds a hotspot, and runs when the gauntlet plugin is importable
and a .gauntlet/graph.db exists. Without them, Tiers 2 and 3
no-op and Tier 1 still produces findings on Python source.
Quick Start
/performance-review # scan changed files
/performance-review path/to/file.py # scan one file
/performance-review --tier 1 # force Tier 1 only
Programmatic use:
from pensive.skills.performance_review import PerformanceReviewSkill
skill = PerformanceReviewSkill()
result = skill.analyze(context, "src/module.py")
for f in result.issues:
print(f"[{f.severity}] {f.file}:{f.line} {f.message}")
When To Use
- Pre-merge review of code that runs on user-scaled inputs.
- Triage of a function that "feels slow" before reaching for a profiler.
- Audit a refactor for newly introduced O(n²) patterns.
- Guardrail for AI-generated code where nested-loop hot spots are common.
When NOT to Use
- The target needs runtime measurement (memory profile, CPU
time on real data). Use
Skill(parseltongue:python-performance)instead: that skill drivescProfile,py-spy, and benchmarks. - General refactoring guidance not focused on hotspots: use
Skill(pensive:code-refinement)whosealgorithm-efficiencymodule covers broader optimization patterns. This skill detects, and that skill teaches. - Deciding whether a hand-rolled loop transform (unrolling, manual
SIMD, strength reduction) is worth keeping: use
Skill(leyline:loop-optimization)for the hand-vs-compiler rule. This skill flags hotspot shapes and leaves the transform choice to that skill. - Architecture-level performance (sharding, caching layers,
queue placement): use
Skill(pensive:architecture-review).
Required Progress Items
perf-review:context-establishedperf-review:scan-completeperf-review:findings-categorizedperf-review:integration-checkedperf-review:report-generatedperf-review:findings-verified
Workflow
Step 1: Context (perf-review:context-established)
- Identify target files. If invoked with no argument, use
git diff --name-only. If invoked with a path, scope to that. - Note language(s) involved. Tier 1 covers Python. Non-Python
files need the
tiersextra for Tier 2 coverage.
Step 2: Tier 1 AST scan (perf-review:scan-complete)
Load modules/time-complexity.md for the time-side patterns and
modules/space-complexity.md for space-side. Each module
documents the AST shape of every detector.
Alongside the automated scan, load
modules/memory-allocation-lenses.md and apply its three
manual lenses (unbounded external-source collections, hot-path
recompute, serial blocking I/O) by reading the target files.
For each Python target file, call:
from pensive.skills.performance_review import PerformanceReviewSkill
result = PerformanceReviewSkill().analyze(context, path)
The visitor walks the AST once and emits ReviewFinding records.
Step 3: Categorize and rank (perf-review:findings-categorized)
Group findings by severity:
- HIGH: O(n²) or worse on input-sized iterables (T1, T2).
- MEDIUM: Unbounded allocation or per-iteration overhead (T3, T4, S1, S3).
- LOW: Style-level inefficiencies (T5, T6, S2).
- CRITICAL: Reserved for Tier-3 transitive upgrades.
Within a severity, sort by file then line. Suppress findings the user has explicitly marked acceptable (TODO/comment markers) at module-load time of the target.
Step 4: Tier 2/3 enrichment (perf-review:integration-checked)
Load modules/gauntlet-integration.md for the contract.
If tree_sitter_language_pack is importable, run Tier 2 on
non-Python files that were skipped at Step 2. If gauntlet is
importable and a .gauntlet/graph.db exists in the scanned
file's directory or any parent, run Tier 3 to upgrade severities
based on hotspots in transitive callees.
Without the extra, this step is a no-op and the report notes
"Tier 2/3 not available: install pensive with the tiers extra
for multi-language and call-chain coverage." A file that
tree-sitter cannot parse adds a warning and yields no Tier 2
findings.
Step 5: Report (perf-review:report-generated)
Emit a markdown report:
## Performance Review: <target>
### HIGH (<count>)
- src/foo.py:42: Nested loop over the same iterable 'items'.
Suggestion: sort + two pointers, or hash-set membership.
### MEDIUM (<count>)
- ...
### LOW (<count>)
- ...
Tier coverage: 1 (always) | 2 (gauntlet ✓/✗) | 3 (graph ✓/✗)
The report is informational. Apply fixes via
Skill(pensive:code-refinement) or hand-merge.
Tiered Analysis
| Tier | Source | When it runs | What it covers |
|---|---|---|---|
| 1 | stdlib ast | Always (Python source only) | T1-T6, S1-S3 |
| 2 | tree_sitter_language_pack | When importable, non-Python files | T1, T2, S1 on JS/TS, Go, Rust, Java, C/C++ (Java and C: T1 only) |
| 3 | gauntlet.graph.GraphStore | When importable and .gauntlet/graph.db is found above the file | One-step severity upgrade when a CALLS-reachable function holds a hotspot |
Output Format
Findings use the shared ReviewFinding dataclass from
pensive.skills.base:
ReviewFinding(
file="src/module.py",
line=42,
severity="HIGH", # LOW | MEDIUM | HIGH | CRITICAL
category="time", # time | space
message="Nested loop over the same iterable 'items'.",
suggestion="Sort + two pointers, or hash-set membership.",
anchor="verbatim source text at file:line",
code_snippet="",
)
This shape matches every other pensive review skill, so the
findings can flow into Skill(pensive:unified-review) without
translation.
Cross-Plugin Dependencies
| Dependency | Required? | Effect when missing |
|---|---|---|
tree_sitter_language_pack | Optional (tiers extra) | Tier 2 returns []; Python coverage unchanged |
gauntlet.graph.GraphStore | Optional (gauntlet plugin, not on PyPI) | Tier 3 returns []; severities are not upgraded |
The optional-import contract follows the precedent in
plugins/leyline/src/leyline/tokens.py:34-42: try-import to a
module-level sentinel, then early-return on None inside each
tier helper. plugins/gauntlet/hooks/precommit_gate.py:35-40
is the boolean-flag variant of the same shape. See
modules/gauntlet-integration.md for the exact code shape.
Supporting Modules
modules/time-complexity.md: T1-T6 detector patterns and AST shapes.modules/space-complexity.md: S1-S3 detector patterns.modules/gauntlet-integration.md: Tier 2/3 contract, fallback semantics, examples.modules/kuva-visualization.md: Rendering benchmark data as charts with kuva (criterion, pytest-benchmark, ad-hoc tables). Covers when chart evidence satisfies proof-of-work requirements.modules/memory-allocation-lenses.md: Manual review lenses (not AST detectors) for unbounded collections fed from external sources, hot-path recompute that should be memoized, and serial blocking I/O over unbounded sets. Apply by reading the code. The detector-test rule in Testing does not cover these because nothing is automated.
Verification
A perf-review finding is only useful if the caller can confirm it is real. Use this checklist before treating any finding as worth fixing:
- Reproduce under a profiler. Run
cProfile,py-spy, or the language-specific equivalent on the hotspot. The findings pinpoint AST shapes, and the profiler validates the runtime impact. - Re-run the failing benchmark. If
benches/exists, the hotspot should show up in benchmark numbers as well as AST scans. - Compare numbers before and after the proposed fix. The fix
is wrong if numbers do not move. Capture both timings as
evidence references like
[E1](before) and[E2](after). When 3+ data points exist, render a kuva chart and attach it to the PR (seemodules/kuva-visualization.md). - Sample two or three reported hotspots manually. Findings can be true at the AST level and false at the call-graph level when callers short-circuit. Manual sampling catches that.
The Skill(imbue:proof-of-work) discipline applies: claims like
"the hotspot is fixed" require measured evidence.
Testing
A test file already exists at
plugins/pensive/tests/skills/test_performance_review.py covering
the AST-shape detectors. Two rules for changes here:
- Add a new detector with a test. Any new T-* or S-* pattern added to the modules ships with a test that has the smallest AST sample exercising it.
- Add a regression test for any false positive removed. When the skill stops firing on a shape that used to look hot, the reason should appear as a test case so the regression is discoverable later.
The Iron Law applies: a new detector without a failing test first is a request to skip TDD on a code-analysis component, which is exactly the place where TDD pays off most.
Verify Findings Are Grounded (perf-review:findings-verified)
Write findings to .review/findings.json, run the citation verifier
(Skill(imbue:review-core) Step 5), and drop or label UNVERIFIED any
the verifier rejects.
Exit Criteria
- A perf-review report file exists for the requested target.
- Every finding carries a severity label and a concrete suggestion the caller can act on.
- Time-complexity (T1-T6) and space-complexity (S1-S3) detectors have been run, and tier coverage is reported.
- Tier 2 (tree-sitter) and Tier 3 (graph store)
contracts honor the optional-import sentinel: missing
modules return
[]rather than raising. - Each new detector ships with a smallest-AST test that fails before the detector exists, and each removed false positive ships with a regression test.
- Findings flow into
Skill(pensive:unified-review)without translation when invoked from the unified entry point. - Every reported finding carries a
Location+ verbatimAnchorconfirmed bycitation_verifier.py(exit0), or unverified findings were dropped or labeledUNVERIFIED
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/athola/claude-night-market/performance-review">View performance-review on skillZs</a>