performance-gate

name	performance-gate
description	Verifies performance including N+1 query detection, scalability assessment, and complexity analysis. WARNING gate triggered during /own:done flow.

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.