performance-gate

# Gate 4: Performance Review

> "Code that works is step one. Code that scales is step two."

## Purpose

This gate catches performance anti-patterns before they cause problems. The focus is on obvious issues, not micro-optimizations.

## Gate Status

- **PASS** — No obvious performance issues
- **WARNING** — Issues found that could cause problems at scale

---

## Gate Questions

### Question 1: Scalability
> "What happens when there are 10,000 items? 1,000,000?"

**Looking for:**
- Awareness of data growth
- Pagination for large datasets
- Efficient data structures
- No unnecessary loops

### Question 2: Query Efficiency
> "How many database queries does this operation make?"

**Looking for:**
- No N+1 queries
- Bulk operations where appropriate
- Indexes on queried columns
- Awareness of query cost

### Question 3: Re-render Awareness (Frontend)
> "When this state changes, what components re-render?"

**Looking for:**
- Awareness of render triggers
- Appropriate memoization
- State placement optimization
- No expensive computations in render

---

## Performance Checklist

### Database Operations
- [ ] No N+1 queries (queries inside loops)
- [ ] Pagination for list endpoints
- [ ] Indexes on frequently queried columns
- [ ] SELECT only needed columns (not SELECT *)

### Frontend Rendering
- [ ] Expensive computations use useMemo
- [ ] Event handlers use useCallback where needed
- [ ] Large lists use virtualization
- [ ] Heavy components are lazy loaded

### API & Network
- [ ] Response payloads are minimal
- [ ] Large data is paginated
- [ ] Caching headers where appropriate
- [ ] No redundant API calls

### General
- [ ] No nested loops (O(n²)) without justification
- [ ] No blocking operations
- [ ] Cleanup of intervals/timeouts
- [ ] Reasonable memory usage

---

## Response Templates

### If PASS

```
✅ PERFORMANCE GATE: PASSED

Performance considerations look good:
- Data fetching is efficient
- No obvious N+1 patterns
- Appropriate pagination in place

Moving to the next gate...
```

### If WARNING

```
⚠️ PERFORMANCE GATE: WARNING

Found [X] performance concerns:

**Issue 1: [N+1 Query / Inefficient Loop]**
Location: `file.ts:42`
Question: "This makes [N] queries. Can we batch into 1?"

**Issue 2: [Missing Pagination]**
Location: `file.ts:88`
Question: "What happens with 100,000 records?"

**Issue 3: [Expensive Render]**
Location: `Component.tsx:15`
Question: "Does this need to recalculate on every render?"

These may not matter now, but will become problems as the app grows.
```

---

## Common Issues to Check

### 1. The N+1 Query Problem
```
❌ const users = await User.findAll();
   for (const user of users) {
     user.posts = await Post.findByUserId(user.id);
   }
   // 1 + N queries!

✅ const users = await User.findAll({
     include: [{ model: Post }]
   });
   // 1 query with JOIN
```

### 2. Fetching Everything
```
❌ // Returns 10,000 users with 50 fields each
   GET /api/users

✅ // Paginated with only needed fields
   GET /api/users?page=1&limit=20&fields=id,name,email
```

### 3. Expensive Render Calculations
```
❌ function UserList({ users }) {
     // Runs on every render
     const sorted = users.sort((a, b) => a.name.localeCompare(b.name));
     return <ul>{sorted.map(...)}</ul>;
   }

✅ function UserList({ users }) {
     const sorted = useMemo(
       () => [...users].sort((a, b) => a.name.localeCompare(b.name)),
       [users]
     );
     return <ul>{sorted.map(...)}</ul>;
   }
```

### 4. Inline Functions Causing Re-renders
```
❌ function Parent() {
     return <Child onClick={() => doSomething()} />;
     // New function every render → Child re-renders
   }

✅ function Parent() {
     const handleClick = useCallback(() => doSomething(), []);
     return <Child onClick={handleClick} />;
   }
```

### 5. Missing Cleanup
```
❌ useEffect(() => {
     const interval = setInterval(fetchData, 5000);
     // Memory leak! Runs forever
   }, []);

✅ useEffect(() => {
     const interval = setInterval(fetchData, 5000);
     return () => clearInterval(interval);
   }, []);
```

---

## Socratic Performance Questions

Instead of pointing out the fix, ask:

1. "How many queries does this endpoint execute for 100 users?"
2. "If I add 10,000 more items, what breaks?"
3. "Does this array get re-sorted on every render?"
4. "What clears this interval when the component unmounts?"
5. "Do we need all 50 columns from this table?"

---

## Big O Quick Reference

| Pattern | Complexity | 10,000 items | Concern Level |
|---------|------------|--------------|---------------|
| Map lookup | O(1) | 1 op | Fine |
| Single loop | O(n) | 10,000 ops | Usually fine |
| Nested loop | O(n²) | 100M ops | Warning |
| Triple loop | O(n³) | 1T ops | Critical |

---

## Performance Red Flags

| Flag | Question | Why |
|------|----------|-----|
| Query in a loop | "Can we batch?" | N+1 problem |
| No pagination | "What at scale?" | Memory/time explosion |
| SELECT * | "Need all fields?" | Wasted bandwidth |
| setInterval no cleanup | "What clears this?" | Memory leak |
| Inline object/function in JSX | "New reference?" | Unnecessary re-renders |
| Array.sort() in render | "Cached?" | Runs every render |

---

## When to NOT Worry

Not everything needs optimization:

- **Small datasets**: Don't paginate 20 items
- **Rare operations**: One-time admin scripts can be slow
- **Prototype phase**: Get it working first
- **Micro-optimizations**: Focus on algorithms, not `for` vs `forEach`

The gate is about catching **obvious** issues, not micro-optimization.