@smicolon/ai-kit 0.1.0 → 0.1.1

package/packs/django/skills/performance-optimizer/SKILL.md

@@ -0,0 +1,447 @@
+---
+name: performance-optimizer
+description: This skill should be used when the user asks to "optimize queries", "fix slow queries", "improve performance", "detect N+1", "add indexes", or when writing Django ORM queries that access related objects. Detects and fixes performance issues.
+---
+
+# Performance Optimizer
+
+Auto-detects and fixes Django ORM performance issues before they reach production.
+
+## Activation Triggers
+
+This skill activates when:
+- Writing ORM queries
+- Accessing related objects (foreign keys, M2M)
+- Creating views that fetch data
+- Mentioning "slow", "performance", "optimization"
+- Looping over querysets
+- Creating list/detail views
+
+## Performance Targets
+
+- ✅ NO N+1 queries
+- ✅ Appropriate indexes on frequently queried fields
+- ✅ Pagination for list endpoints
+- ✅ `select_related()` for foreign keys
+- ✅ `prefetch_related()` for reverse foreign keys and M2M
+- ✅ Caching for expensive operations
+
+## Auto-Detection Patterns
+
+### Pattern 1: N+1 Query Detection
+
+**❌ INEFFICIENT (N+1 query):**
+```python
+# Bad: 1 query for users + N queries for organizations
+users = User.objects.all()  # 1 query
+for user in users:  # N queries
+    print(user.organization.name)  # Hits DB each time!
+```
+
+**✅ OPTIMIZED:**
+```python
+# Good: 2 queries total (1 for users + 1 JOIN for organizations)
+users = User.objects.select_related('organization').all()
+for user in users:
+    print(user.organization.name)  # No DB hit!
+```
+
+### Pattern 2: Reverse Foreign Key N+1
+
+**❌ INEFFICIENT:**
+```python
+# Bad: 1 + N queries
+organizations = Organization.objects.all()  # 1 query
+for org in organizations:  # N queries
+    users = org.users.all()  # Hits DB each time!
+    print(f"{org.name}: {users.count()} users")
+```
+
+**✅ OPTIMIZED:**
+```python
+# Good: 2 queries total
+organizations = Organization.objects.prefetch_related('users').all()
+for org in organizations:
+    users = org.users.all()  # Pre-fetched!
+    print(f"{org.name}: {users.count()} users")
+```
+
+### Pattern 3: Many-to-Many N+1
+
+**❌ INEFFICIENT:**
+```python
+# Bad: 1 + N queries
+users = User.objects.all()  # 1 query
+for user in users:  # N queries
+    roles = user.roles.all()  # Hits DB each time!
+```
+
+**✅ OPTIMIZED:**
+```python
+# Good: 2 queries total
+users = User.objects.prefetch_related('roles').all()
+for user in users:
+    roles = user.roles.all()  # Pre-fetched!
+```
+
+### Pattern 4: Missing Indexes
+
+**❌ SLOW:**
+```python
+# Frequent query without index
+User.objects.filter(email='test@example.com')  # Table scan if no index!
+```
+
+**✅ FAST:**
+```python
+# Model with index
+class User(models.Model):
+    email = models.EmailField(unique=True)  # Unique creates index
+    # OR
+    class Meta:
+        indexes = [
+            models.Index(fields=['email']),  # Explicit index
+        ]
+```
+
+### Pattern 5: Missing Pagination
+
+**❌ DANGEROUS:**
+```python
+# Returns ALL records - memory issues with large tables
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()  # No pagination!
+```
+
+**✅ SAFE:**
+```python
+# Paginated automatically
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()
+    pagination_class = PageNumberPagination  # DRF auto-paginates
+```
+
+## Auto-Fix Process
+
+### Step 1: Detect Anti-Pattern
+
+When detecting:
+```python
+def get_users_with_organizations(self):
+    users = User.objects.all()
+    return [
+        {'user': u.email, 'org': u.organization.name}
+        for u in users
+    ]
+```
+
+### Step 2: Analyze Query Pattern
+
+Identify:
+- Queryset: `User.objects.all()` (1 query)
+- Foreign key access: `u.organization.name` (N queries)
+- **Total:** 1 + N queries = N+1 problem!
+
+### Step 3: Suggest Optimization
+
+Provide:
+
+> **N+1 Query Detected!**
+>
+> **Problem:**
+> - Query: `User.objects.all()` → 1 query
+> - Loop accesses `user.organization.name` → N queries
+> - **Total:** 1 + N queries (inefficient!)
+>
+> **Impact:**
+> - 100 users = 101 queries 😱
+> - 1000 users = 1001 queries 🔥
+>
+> **Fix:**
+> ```python
+> users = User.objects.select_related('organization').all()
+> # Now only 2 queries total!
+> ```
+>
+> **Why:**
+> - `select_related()` performs SQL JOIN
+> - Fetches related data in single query
+> - 500x faster for 1000 records!
+
+### Step 4: Auto-Apply Fix
+
+```python
+# Optimized version
+def get_users_with_organizations(self):
+    users = User.objects.select_related('organization').all()
+    return [
+        {'user': u.email, 'org': u.organization.name}  # No DB hit!
+        for u in users
+    ]
+```
+
+## Common Optimization Patterns
+
+### Foreign Key (One-to-One, Many-to-One)
+
+```python
+# Use select_related() for foreign keys
+User.objects.select_related('organization', 'created_by')
+
+# Multiple levels
+User.objects.select_related('organization__country')
+```
+
+### Reverse Foreign Key (One-to-Many)
+
+```python
+# Use prefetch_related() for reverse FK
+Organization.objects.prefetch_related('users')
+
+# With filtering
+from django.db.models import Prefetch
+Organization.objects.prefetch_related(
+    Prefetch('users', queryset=User.objects.filter(is_active=True))
+)
+```
+
+### Many-to-Many
+
+```python
+# Use prefetch_related() for M2M
+User.objects.prefetch_related('roles', 'permissions')
+```
+
+### Combined Optimization
+
+```python
+# Optimize multiple relations
+users = User.objects.select_related(
+    'organization',  # FK
+    'created_by'     # FK
+).prefetch_related(
+    'roles',         # M2M
+    'permissions'    # M2M
+)
+```
+
+## Index Recommendations
+
+Suggest indexes for:
+
+### Frequently Filtered Fields
+
+```python
+class User(models.Model):
+    email = models.EmailField()
+    status = models.CharField(max_length=20)
+
+    class Meta:
+        indexes = [
+            models.Index(fields=['email']),    # WHERE email = ...
+            models.Index(fields=['status']),   # WHERE status = ...
+        ]
+```
+
+### Composite Indexes
+
+```python
+class Order(models.Model):
+    user = models.ForeignKey(User)
+    status = models.CharField(max_length=20)
+    created_at = models.DateTimeField()
+
+    class Meta:
+        indexes = [
+            # Composite index for common query pattern
+            models.Index(fields=['user', 'status']),
+            # Index for time-based queries
+            models.Index(fields=['-created_at']),  # DESC order
+        ]
+```
+
+### Foreign Key Indexes
+
+```python
+# Django automatically creates indexes for:
+# - Primary keys
+# - Unique fields
+# - Foreign keys
+
+# Manual indexes needed for:
+# - Composite queries
+# - Ordering fields
+# - Search fields
+```
+
+## Caching Strategies
+
+### Query Caching
+
+```python
+from django.core.cache import cache
+
+def get_active_users():
+    cache_key = 'active_users'
+    users = cache.get(cache_key)
+
+    if users is None:
+        users = list(User.objects.filter(is_active=True).values())
+        cache.set(cache_key, users, 300)  # Cache 5 minutes
+
+    return users
+```
+
+### Model Method Caching
+
+```python
+from django.utils.functional import cached_property
+
+class User(models.Model):
+    @cached_property
+    def full_name(self):
+        """Expensive computation cached per instance."""
+        return f"{self.first_name} {self.last_name}".strip()
+```
+
+## Pagination Patterns
+
+```python
+# DRF Pagination
+from rest_framework.pagination import PageNumberPagination
+
+class StandardResultsSetPagination(PageNumberPagination):
+    page_size = 100
+    page_size_query_param = 'page_size'
+    max_page_size = 1000
+
+class UserViewSet(viewsets.ModelViewSet):
+    pagination_class = StandardResultsSetPagination
+```
+
+## Database Query Analysis
+
+Check queries using Django Debug Toolbar patterns:
+
+```python
+from django.db import connection
+from django.test.utils import override_settings
+
+@override_settings(DEBUG=True)
+def test_user_list_queries(self):
+    """Test that user list doesn't have N+1 queries."""
+    with self.assertNumQueries(2):  # Should be exactly 2 queries
+        response = self.client.get('/api/users/')
+        # 1 query: Fetch users
+        # 1 query: Fetch organizations (prefetched)
+```
+
+## Performance Checklist
+
+For every queryset, verify:
+
+- ✅ `select_related()` for accessed foreign keys
+- ✅ `prefetch_related()` for reverse FKs and M2M
+- ✅ `.only()` or `.defer()` if fetching many fields
+- ✅ Indexes on filtered/ordered fields
+- ✅ Pagination for lists
+- ✅ `.count()` instead of `len(queryset)`
+- ✅ `.exists()` instead of `if queryset`
+- ✅ Bulk operations instead of loops
+
+## Before/After Examples
+
+### Example 1: User List with Organization
+
+**❌ Before (N+1):**
+```python
+# views.py
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()  # 1 query
+    # serializer accesses user.organization.name → N queries
+```
+
+**✅ After (Optimized):**
+```python
+# views.py
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.select_related('organization').all()  # 2 queries total
+```
+
+### Example 2: Organization with Users
+
+**❌ Before (N+1):**
+```python
+def organization_summary(self):
+    orgs = Organization.objects.all()  # 1 query
+    return [
+        {
+            'name': org.name,
+            'user_count': org.users.count()  # N queries!
+        }
+        for org in orgs
+    ]
+```
+
+**✅ After (Optimized):**
+```python
+from django.db.models import Count
+
+def organization_summary(self):
+    orgs = Organization.objects.annotate(
+        user_count=Count('users')  # Single query with aggregation
+    ).all()
+    return [
+        {
+            'name': org.name,
+            'user_count': org.user_count  # No DB hit!
+        }
+        for org in orgs
+    ]
+```
+
+## Integration with Testing
+
+```python
+# Test that optimizations work
+@pytest.mark.django_db
+def test_user_list_performance(django_assert_num_queries):
+    """User list should use select_related to avoid N+1."""
+    UserFactory.create_batch(100)  # Create 100 users
+
+    with django_assert_num_queries(2):  # Only 2 queries allowed
+        users = list(User.objects.select_related('organization').all())
+        for user in users:
+            _ = user.organization.name  # Should not hit DB
+```
+
+## Success Criteria
+
+✅ NO N+1 queries in codebase
+✅ All foreign key access uses `select_related()`
+✅ All reverse FK/M2M use `prefetch_related()`
+✅ Appropriate indexes on all models
+✅ Pagination on all list endpoints
+✅ Bulk operations used instead of loops
+
+## Behavior
+
+**Proactive enforcement:**
+- Detect N+1 queries automatically
+- Suggest optimizations immediately
+- Calculate performance impact (queries before/after)
+- Add indexes to models
+- Explain WHY the optimization matters
+
+**Never:**
+- Require explicit "optimize queries" request
+- Wait for production slowness
+- Just warn without fixing
+
+**Block completion if:**
+- N+1 queries detected
+- Missing indexes on frequently queried fields
+- No pagination on list endpoints
+- Bulk creates/updates done in loops
+
+This ensures code is performant from day one.

package/packs/django/skills/red-phase-verifier/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: red-phase-verifier
+description: This skill should be used when the user asks to "write tests first", "run TDD", "verify red phase", "check failing tests", or when practicing test-driven development. Ensures tests fail before implementation.
+---
+
+# Red Phase Verifier
+
+Ensures tests are written BEFORE implementation and fail initially.
+
+## Purpose
+
+In TDD:
+1. **RED**: Write failing tests
+2. **GREEN**: Implement to pass
+3. **REFACTOR**: Improve while green
+
+This skill enforces Step 1.
+
+## Activation Triggers
+
+This skill activates when:
+- Running /dev-loop command
+- Creating test files before implementation
+- Mentioning "write tests first"
+
+## Verification Process
+
+### Step 1: Check Implementation Exists
+
+```python
+# If implementing UserService.create_user:
+# Check if method exists and has logic
+
+import inspect
+from app.services import UserService
+
+method = getattr(UserService, 'create_user', None)
+if method:
+    source = inspect.getsource(method)
+    if 'pass' not in source and 'raise NotImplementedError' not in source:
+        # Implementation exists!
+        WARN: "Implementation found before tests"
+```
+
+### Step 2: Run Tests
+
+```bash
+pytest tests/test_new_feature.py -v --tb=short
+```
+
+### Step 3: Verify Failures
+
+Expected output:
+```
+FAILED tests/test_new_feature.py::test_create - AssertionError
+FAILED tests/test_new_feature.py::test_validate - AttributeError
+```
+
+### Step 4: Report
+
+```
+RED PHASE VERIFICATION
+
+Tests written: 5
+Tests failing: 5
+
+Red phase confirmed!
+Implementation may now proceed.
+```
+
+## Warning Cases
+
+### Case 1: Tests Pass Before Implementation
+
+```
+WARNING: Tests passed before implementation!
+
+Failing tests: 0/5
+
+This indicates:
+1. Tests don't test new functionality
+2. Tests have trivial assertions
+3. Implementation already exists
+
+Action: Regenerate stricter tests
+```
+
+### Case 2: Partial Failures
+
+```
+PARTIAL RED PHASE
+
+Tests failing: 3/5
+Tests passing: 2/5
+
+Passing tests may be:
+1. Testing existing functionality (OK)
+2. Trivial assertions (NOT OK)
+
+Review passing tests:
+- test_helper_exists: assert helper <- TRIVIAL
+- test_constant: assert X == X <- TRIVIAL
+
+Action: Strengthen or remove trivial tests
+```
+
+### Case 3: Wrong Failure Type
+
+```
+UNEXPECTED FAILURE TYPE
+
+test_create_user: SyntaxError in test file
+
+Tests should fail due to:
+- AssertionError (expected behavior not met)
+- AttributeError (method doesn't exist yet)
+- NotImplementedError (placeholder)
+
+NOT due to:
+- SyntaxError (test file broken)
+- ImportError (missing dependency)
+- TypeError (wrong arguments)
+
+Action: Fix test file syntax
+```
+
+## Enforcement
+
+When red phase not verified:
+
+```
+CANNOT PROCEED TO GREEN PHASE
+
+Red phase requirements not met:
+- 2 tests passed before implementation
+- 1 test has syntax error
+
+Fix issues, then run verification again.
+```
+
+## Expected Failure Types
+
+### Good Failures (Proceed)
+
+- `AssertionError` - Assertion failed (expected)
+- `AttributeError` - Method/attribute doesn't exist yet
+- `NotImplementedError` - Placeholder implementation
+- `ModuleNotFoundError` - Module not created yet
+
+### Bad Failures (Fix First)
+
+- `SyntaxError` - Test code is broken
+- `IndentationError` - Test code formatting issue
+- `NameError` - Undefined variable in test
+- `TypeError` - Wrong arguments in test setup
+
+## Dev Loop Integration
+
+When integrated with /dev-loop:
+
+1. Tests written -> Run red phase verifier
+2. If all fail correctly -> Proceed to implementation
+3. If some pass -> Warn and suggest fixes
+4. If wrong failures -> Block until fixed
+
+```
+TDD LOOP: RED PHASE
+
+Running red phase verification...
+
+test_create_user: FAILED (AttributeError)
+test_validate_email: FAILED (AssertionError)
+test_duplicate_email: FAILED (AssertionError)
+test_get_user: FAILED (NotImplementedError)
+test_list_users: FAILED (NotImplementedError)
+
+Red phase: 5/5 tests failing correctly
+
+Proceeding to GREEN phase...
+```