review-perf · diff
v1.0.0 to v1.2.0
80 added, 134 removed. Audit A to A.
---
name: review-perf
- description: Perform comprehensive performance review analyzing database queries,
- algorithmic complexity, frontend bottlenecks, and resource leaks for PRs, commits,
- or entire codebases. This skill should be used when a user wants to audit code performance,
- identify bottlenecks, review query efficiency, or check for memory leaks. Analysis
- only - identifies issues without modifying code.
+ description: Deep-dive performance audit of database queries, algorithmic complexity,
+ frontend bottlenecks, and resource leaks for a PR, a commit, or the whole codebase,
+ producing a severity-ranked report. Use when the user explicitly wants a dedicated
+ performance review, asks to "audit performance", "find N+1 queries", "check for
+ memory leaks", or "review query efficiency" - especially when review-code's single
+ performance dimension isn't thorough enough. Analysis only - identifies issues
+ without modifying, fixing, or committing code. Not for a general six-dimension
+ review where performance is just one concern among several (use review-code), and
+ not for a full multi-agent PR review team (use team-review).
metadata:
author: mgiovani
- version: 1.0.0
- source: https://github.com/mgiovani/skills
+ version: 1.2.0
disable-model-invocation: true
---
- # Review Perf
-
- > **Cross-Platform AI Agent Skill**
- > This skill works with any AI agent platform that supports the skills.sh standard.
-
# Performance Review
- Comprehensive performance analysis targeting database query inefficiencies, algorithmic complexity issues, frontend bottlenecks, and resource leaks. This skill performs **analysis only** - it identifies performance problems, explains findings, and suggests optimization approaches without making code changes.
+ Comprehensive performance analysis targeting database query inefficiencies, algorithmic complexity issues, frontend bottlenecks, and resource leaks. **Analysis only** - identifies problems and suggests optimizations without making code changes.
- ## Anti-Hallucination Guidelines
+ ## Constraints
- **CRITICAL**: Performance reviews must be based on ACTUAL code analysis and VERIFIED patterns:
- 1. **Read before claiming** - Never report performance issues in code that has not been read
- 2. **Evidence-based findings** - Every finding must reference specific file paths and line numbers
- 3. **Pattern matching** - Use Grep to find actual anti-patterns, not hypothetical ones
- 4. **No invented metrics** - Only report measurable or verifiable performance concerns
- 5. **Quantifiable results** - Count actual instances, do not estimate
- 6. **No false positives** - Verify each finding matches documented performance anti-patterns
- 7. **Scope verification** - Only scan files within specified scope (PR/commit/all)
- 8. **Context matters** - A pattern that is slow in a hot path may be acceptable in initialization code
+ - **Analysis only** - never modifies, fixes, or commits code, even if asked to "also fix these" mid-run; report the findings and stop
+ - **Static analysis** - no runtime profiling, no benchmarking, no load testing
+ - **Pattern-based** - Big O and impact estimates are approximate; may miss context-specific issues a profiler would catch
+ - **Not exhaustive** - does not guarantee 100% detection; profiling is recommended before acting on critical findings
+ - **Read before claiming** - never report a finding in a file that has not actually been read; every finding cites the specific file path and line number it came from
+ - **No invented numbers** - counts, query-multiplication estimates, and Big O claims must trace back to code actually read, not generic examples copied from the report template
+ - **Diff-scope confinement** - for a PR or commit review, never grep or read a file the diff didn't touch, and never let a pre-existing issue in a touched file masquerade as a PR finding; see Phase 0/2
## Scan Workflow
### Phase 0: Determine Scan Scope
- Parse arguments to determine what to scan:
+ Parse arguments:
- ```
- Arguments:
- - <pr_number>: Scan only files changed in PR (e.g., "123", "#123")
- - <commit_sha>: Scan only files changed in commit (e.g., "abc123")
- - "--all" or no args: Scan entire codebase
- - "--scope [database|algorithm|frontend|resources|backend]": Focus on specific performance categories
- If PR or commit specified, use Bash to get changed files:
+ - `<pr_number>`: scan only files changed in that PR (e.g. `123`, `#123`)
+ - `<commit_sha>`: scan only files changed in that commit
+ - `--all` or no args: scan entire codebase
+ - `--scope [database|algorithm|frontend|resources|backend]`: focus on specific categories (`backend` = database + algorithm + resources, excludes frontend)
+
+ If PR or commit specified, pull the *full diff* - not just the file list - so hunk ranges are available for Phase 2's confinement check:
+
```bash
# For PR
- gh pr view <pr_number> --json files --jq '.files[].path'
+ gh pr diff <pr_number>
# For commit
- git diff-tree --no-commit-id --name-only -r <commit_sha>
- ### Phase 1: Project Technology Discovery
+ git diff-tree -p <commit_sha>
+ ```
- Explore the codebase to understand the project technology stack:
+ From that diff, extract two things and carry both into Phase 2:
+ 1. **Changed-file list**: the paths after each `+++ b/` line.
+ 2. **Hunk ranges per file**: each `@@ -a,b +c,d @@` header gives the new-file line range `c` to `c+d-1` for that hunk. A file can have multiple hunks.
- ### Phase 2: Initialize Progress Tracking
+ `--all` or no args skips this entirely - there's no diff to confine to, the whole codebase is in scope.
- Use TodoWrite to track comprehensive scan progress across all 4 performance categories, consolidation, and report generation.
+ ### Phase 1: Project Technology Discovery
- ### Phase 3: Parallel Performance Scanning
+ Explore the codebase to identify the stack (language, ORM, framework) - it determines which anti-patterns in [references/agent-prompts.md](references/agent-prompts.md) apply and which profiling tools to recommend.
- Spawn **4 parallel Explore agents** for comprehensive performance analysis. Each agent targets specific performance categories using Grep patterns to find actual anti-patterns in code.
+ ### Phase 2: Scan the Codebase
- For detailed agent prompts and grep patterns for each performance category, see [references/agent-prompts.md](references/agent-prompts.md).
+ Four scan categories, each with its own grep patterns and reporting format in [references/agent-prompts.md](references/agent-prompts.md):
- **Agent assignments:**
- - **Agent 1**: N+1 Queries & Database Performance
- - **Agent 2**: Algorithmic Complexity & Computational Efficiency
- - **Agent 3**: Frontend Bottlenecks (Bundle Size, Rendering, Network)
- - **Agent 4**: Resource Leaks (Memory, Connections, File Handles)
+ - **Database**: N+1 queries, missing indexes, connection management
+ - **Algorithm**: quadratic+ complexity, inefficient data structures, unnecessary recomputation
+ - **Frontend**: bundle size, rendering (React re-renders, layout thrashing), network waterfalls
+ - **Resources**: memory leaks, connection/file-handle leaks, thread/process leaks
- Each agent must:
- 1. Grep for performance anti-patterns across files in scope
- 2. Read each match to verify context (hot path vs. cold path)
- 3. Extract exact code snippets (5-10 lines)
- 4. Explain why the code is a performance concern
- 5. Classify severity (Critical/High/Medium/Low)
- 6. Provide optimization recommendations (2-3 approaches)
- 7. Estimate performance impact where possible (e.g., "O(n²) → O(n log n)")
+ Spawn only the category matching `--scope`; spawn all 4 for `--all`, no scope, or `--scope backend` (database + algorithm + resources).
- ### Phase 4: Consolidate & Analyze Findings
+ With subagent tools available: spawn one Explore agent per category in parallel, using the prompts in the reference file, and track progress with TodoWrite. Without subagent tools: run the categories sequentially inline in the same order, one grep pass and read-verify cycle per category.
- After all agents complete:
+ For a PR or commit review, pass the Phase 0 changed-file list to every category (agent or inline) as the *only* valid grep/read target - a file the diff didn't touch is out of bounds even if it looks relevant (e.g. a service a changed view calls into). For `--all`, there's no such restriction.
- 1. **Collect all findings** from the 4 parallel agents
- 2. **Deduplicate** - Remove duplicate findings across agents
- 3. **Prioritize by severity**:
- - **Critical**: N+1 queries in loops, O(n²+) on large datasets, memory leaks in long-running processes, unbounded resource allocation
- - **High**: Missing database indexes, synchronous blocking in async contexts, large bundle imports, connection pool exhaustion
- - **Medium**: Suboptimal queries, unnecessary re-renders, missing caching opportunities, inefficient data structures
- - **Low**: Minor optimization opportunities, style preferences with marginal impact
- 4. **Categorize by performance domain**: Group findings under Database, Algorithm, Frontend, Resources
- 5. **Statistics**: Count total issues, by severity, by category, files scanned vs files with issues
- 6. **Impact assessment**: Estimate overall performance impact and prioritize quick wins
+ Each category, agent or inline:
+ 1. Grep for the anti-patterns for that category, restricted to the changed-file list on a PR/commit review
+ 2. Read each match to verify context (hot path vs. cold path - a slow pattern in init code is not the same finding as one in a request handler)
+ 3. On a PR/commit review, check the match's line number against that file's hunk ranges from Phase 0:
+ - Inside a hunk → a PR finding, goes through steps 4-6 into the main Findings section
+ - Outside every hunk (pre-existing code in a touched file) → skip steps 4-6's severity/fix writeup and instead route it to the separate "Pre-existing issues" bucket (Phase 4); never mix it into the main findings
+ 4. Extract the exact code snippet (5-10 lines)
+ 5. Classify severity (Critical/High/Medium/Low) and explain why
+ 6. Give 2-3 optimization approaches
+ 7. Estimate impact where the code supports it (e.g. "O(n²) → O(n log n)", "101 queries → 2 queries for 100 records")
- ### Phase 5: Generate Performance Report
+ ### Phase 3: Consolidate & Prioritize
- Generate a comprehensive markdown report following the template in [references/report-template.md](references/report-template.md).
+ 1. Collect findings from all categories scanned; deduplicate anything two categories both flagged
+ 2. On a PR/commit review, keep the pre-existing-issues bucket separate from the main findings throughout - it never enters the severity tally below
+ 3. Sort by severity:
+ - **Critical**: N+1 in loops, O(n²+) on large datasets, memory leaks in long-running processes, unbounded resource allocation
+ - **High**: missing indexes, sync blocking in async contexts, large bundle imports, connection pool exhaustion
+ - **Medium**: suboptimal queries, unnecessary re-renders, missing caching, inefficient data structures
+ - **Low**: minor optimizations, marginal-impact style preferences
+ 4. Group by domain (Database/Algorithm/Frontend/Resources) and compute stats: total issues, by severity, by category, files scanned vs. files with issues
- ### Phase 6: Verification & Quality Check
+ ### Phase 4: Generate Report
- Before presenting report, verify:
- 1. Every finding has file path and line numbers
- 2. Every finding has actual code snippet (not placeholder)
- 3. Every finding has clear explanation of the performance impact
- 4. Every finding has 2-3 optimization approaches with examples
- 5. Statistics are accurate (counted, not estimated)
- 6. No duplicate findings
- 7. Severity ratings are justified with reasoning
- 8. Only scanned files within specified scope
- 9. No invented issues or false positives
- 10. Big O complexity claims are accurate
- 11. Profiling tool recommendations match the technology stack
+ Follow [references/report-template.md](references/report-template.md). Every number in it (finding counts, severity totals, file:line refs) must come from Phase 3's actual tally - never fill in the template's placeholder numbers as if they were real.
+ On a PR/commit review with a non-empty pre-existing-issues bucket, add a "Pre-existing Issues Noticed in Touched Files (outside this PR's changes)" section after the main Findings section - same file:line/snippet/severity format, clearly separated, excluded from the Severity Breakdown and Performance Impact Summary counts (which cover main findings only). If the bucket is empty, omit the section rather than writing a placeholder.
+
+ After writing the Findings sections, recount: count the actual Finding entries present in the report (per category and per severity) and use that recount for the Severity Breakdown and Performance Impact Summary table. Never estimate the summary counts or carry forward Phase 3's tally unreconciled - if a finding was dropped or merged while writing the report, the totals must reflect what's actually written, not what was originally found.
+
## Usage
```bash
- # Scan specific PR
- review-perf 123
+ review-perf 123 # scan PR 123
review-perf #456
-
- # Scan specific commit
- review-perf abc123def
-
- # Scan entire codebase
- review-perf --all
- review-perf
-
- # Focus on specific scope
- review-perf --all --scope database
- review-perf 123 --scope frontend
- ## Scope Options
-
- - `database`: Focus on N+1 queries, missing indexes, inefficient queries, connection management
- - `algorithm`: Focus on Big O complexity, data structure choices, unnecessary computation
- - `frontend`: Focus on bundle size, rendering performance, network optimization, Core Web Vitals
- - `resources`: Focus on memory leaks, connection pools, file handle management, thread safety
- - `backend`: Focus on database + algorithm + resources (excludes frontend)
-
- If no scope specified, perform comprehensive scan across all categories.
+ review-perf abc123def # scan a commit
+ review-perf --all # scan entire codebase
+ review-perf # same as --all
+ review-perf --all --scope database # codebase-wide, database findings only
+ review-perf 123 --scope frontend # PR 123, frontend findings only
+ ```
## Additional Resources
- - [references/agent-prompts.md](references/agent-prompts.md) - Detailed grep patterns and agent prompts for each performance category
- - [references/report-template.md](references/report-template.md) - Full markdown report template with all sections
-
- ## What This Skill Does
-
- - Identifies database query inefficiencies (N+1, missing indexes, full table scans)
- - Analyzes algorithmic complexity and suggests optimal alternatives
- - Detects frontend bottlenecks (bundle bloat, render thrashing, layout shifts)
- - Finds resource leaks (memory, connections, file handles)
- - Provides detailed explanations with Big O analysis
- - Suggests multiple optimization approaches with code examples
- - Generates comprehensive markdown report with profiling recommendations
- - Prioritizes findings by severity and estimated impact
-
- ## What This Skill Does NOT Do
-
- - Does not modify any code
- - Does not automatically fix performance issues
- - Does not commit changes
- - Does not run runtime profiling or benchmarks
- - Does not perform load testing
- - Does not guarantee 100% performance issue detection
-
- ## Limitations
-
- - **Static analysis only**: Cannot detect runtime-only performance issues
- - **Pattern-based**: May miss context-specific performance problems
- - **No runtime profiling**: Cannot measure actual execution time or memory usage
- - **No load testing**: Cannot test performance under concurrent users
- - **Estimates are approximate**: Big O analysis may not reflect real-world data sizes
- - **Requires manual verification**: Profiling recommended for critical performance claims
+ - [references/agent-prompts.md](references/agent-prompts.md) - grep patterns and per-category scan prompts (load in Phase 2)
+ - [references/report-template.md](references/report-template.md) - full markdown report template (load in Phase 4)
## Performance References
- [Web Vitals](https://web.dev/vitals/) - Core Web Vitals metrics and thresholds
- [React Performance](https://react.dev/learn/render-and-commit) - React rendering optimization
- [Database Query Optimization](https://use-the-index-luke.com/) - SQL indexing and query patterns
- - [Memory Management Best Practices](https://developer.chrome.com/docs/devtools/memory-problems/) - Memory leak detection
+ - [Memory Management Best Practices](https://developer.chrome.com/docs/devtools/memory-problems/) - memory leak detection