---
name: review-perf
description: Performance analysis for algorithmic complexity, memory leaks, N+1 queries, and render issues. Use when code feels slow, after adding loops/queries, or before scaling up.
argument-hint: '[--staged | --unpushed | --changed | --all]'
effort: high
---

# Review Performance

Performance analysis for common bottlenecks and inefficiencies.

## Review grading

Use only these finding priorities, in descending order:

- **Critical Issues (Must Fix):** a verified path causes data loss, a security failure, a materially
  wrong operation, or makes a core workflow unusable without reasonable recovery.
- **Improvements (Should Fix):** an ordinary supported workflow demonstrably fails or repeatedly
  imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
- **Suggestions (Nice to Have):** a worthwhile improvement with small practical impact, including
  optional polish, local simplification, and rare recoverable edge cases.

Grade the demonstrated consequence, realistic reachability, and available recovery against project
priorities. A category, missing convention, hypothetical future problem, or confidence that a claim
is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep
unverified claims in validation gaps, outside the graded finding count; distinguish suggestions
from defects. For plans, trace the consequence if implemented and state the assumptions.

Use the short labels **Must Fix**, **Should Fix**, and **Nice to Have** in summaries and ledgers.
Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings
separate. When called by `code-review`, return its requested evidence and impact fields; the parent
owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.

## Usage

```
/review-perf                  # Review context-related code
/review-perf --staged         # Review staged changes
/review-perf --unpushed       # Review files changed across all unpushed commits
/review-perf --changed        # Review unstaged changes
/review-perf --all            # Full codebase audit (parallel agents)
```

## Scope

| Flag | Scope | Method |
|------|-------|--------|
| (none) | Context-related code | Files from the current conversation context: any files the user has discussed, opened, or that you have read/edited in this session. If no conversation context exists, ask the user to specify files or use `--staged`/`--changed`/`--all`. |
| `--staged` | Staged changes | `git diff --cached --name-only` |
| `--unpushed` | Files changed across unpushed commits | `git diff --name-only $(git rev-list HEAD --not --remotes \| tail -1)^..HEAD` |
| `--changed` | Unstaged changes | `git diff --name-only` |
| `--all` | Full codebase | Glob source files, parallel agents |

`--unpushed` derives its range from `git rev-list HEAD --not --remotes` (oldest unpushed commit's parent → HEAD). If nothing is unpushed, or there is no remote/upstream (or the range walks back to the root commit) so it can't be determined reliably, stop and ask the user to pick another scope.

## Gotchas
- Default scope (no flag) uses conversation context, which may be stale from an earlier part of the session. The review silently targets the wrong files if context has shifted.
- Blindly adding `useMemo`/`useCallback` to fix re-render warnings can worsen performance on simple components — memoization has overhead and only helps when the memoized value is expensive or the child does reference equality checks.

## Workflow

1. **Determine scope** based on flags (see Scope table above)
2. **Review each file** against all 5 categories in the Performance Checklist below: Algorithmic Complexity, Database/Query Patterns, Memory Management, UI/Render Performance, Network/IO
3. **Parallelize** if scope has >5 files: spawn one sub-agent per category, each scanning all files for that category. Merge results and deduplicate.

   Dispatch workers that return findings without editing files. Disable delegation tools where supported; read-only access alone does not prevent delegation. Any coordinating role needs explicit subtasks, a descendant limit, and a stopping condition in its brief.
4. **Classify severity** using Review grading; justify the impact with evidence.
5. **Report findings** grouped by severity using the Output Format below

## Performance Checklist

### Algorithmic Complexity

- Nested loops over the same collection (O(n²) or worse) — replace with a lookup map
- Repeated expensive calculations inside a loop — hoist outside
- Array scans that could exit early — use `.find()` or equivalent

### Database/Query Patterns

- Queries inside loops (N+1) — use eager loading / batch fetch
- Loading all rows without a LIMIT — add pagination
- `SELECT *` when only a few columns are needed — select explicitly
- Missing indexes on columns used in WHERE, ORDER BY, JOIN, or foreign keys

### Memory Management

- Connections, file handles, and subscriptions that accumulate across completed operations — inspect lifetime ownership and cleanup. Lock release, rollback, and cancellation cleanup needed for correct behavior belong to `review-correctness`.
- Caches, queues, and buffers with no effective capacity bound; file/payload reads or pagination that load an entire growing dataset. Trace expected size, lifetime, backpressure, and existing upstream limits before proposing caps, streaming, or pagination. Attacker-controlled exhaustion belongs to `review-security`; non-termination belongs to `review-correctness`.
- Event listeners added without a corresponding removal — return cleanup in `useEffect`

### UI/Render Performance

- Inline object/function literals passed as props causing reference churn — memoize with `useMemo`/`useCallback`
- Long lists rendered without virtualization — use a virtualized list component
- Heavy synchronous computation on the main thread — offload to a web worker or chunk the work

### Network/IO

- Sequential `await` calls for independent requests — use `Promise.all`
- The same request fired multiple times without deduplication — use SWR/React Query or a request cache

For annotated BAD/GOOD code examples for each category, see `references/perf-checklist.md`.

## Output Format

```markdown
## Performance Review: {scope}

### Critical Issues (Must Fix)
- {file}:{line} - {issue type}: {description}
  **Impact:** {why it matters}
  **Fix:** {solution with code example}

### Improvements (Should Fix)
- {file}:{line} - {issue}
  **Fix:** {solution}

### Suggestions (Nice to Have)
- {file} - {issue}

```

## Examples

**Staged changes introduce N+1 query:**
> /review-perf --staged

Reviews staged files and catches a new user list endpoint that queries posts per user in a loop. Records the query count ("100 users = 101 queries") and checks actual sizes and latency. Reports Should Fix when the ordinary path has demonstrated substantial cost; otherwise records a useful optimization as Nice to Have. Resource exhaustion or a core outage needs separate evidence for Must Fix. Suggests eager loading with `include`.

**Full audit finds memory leak in dashboard:**
> /review-perf --all

Parallel agents scan the full codebase by category. Finds an event listener in the dashboard component that is never cleaned up on unmount, plus an unbounded in-memory cache growing with every API call.

## Troubleshooting

### False positive on a rarely-executed code path
**Solution:** If the flagged code runs only during initialization or in admin-only flows, note the expected data size in a code comment. Re-run the review and the context will help distinguish hot paths from cold ones.

### Cannot determine algorithmic complexity without runtime data
**Solution:** Add a brief comment with the expected input size (e.g., `// n is typically < 50`) so static analysis can assess impact. For uncertain cases, use `/perf-test` to measure actual performance with realistic data.

## Notes

- Focus on measurable impact, not micro-optimizations
- Consider data size - O(n²) on 10 items is fine, on 10,000 is not
- For `--all`, use parallel agents per category
- Database issues often have the highest impact
- UI issues matter most for user-facing code
