wicked-garden 12.27.0

package/skills/engineering/backend/refs/checklists.md

@@ -0,0 +1,146 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Backend Review Checklists
+
+## API Quality Checklist
+- [ ] RESTful conventions followed
+- [ ] Appropriate HTTP methods and status codes
+- [ ] Request/response validation
+- [ ] Consistent error responses
+- [ ] Pagination for collections
+- [ ] Versioning strategy
+
+## Database Quality Checklist
+- [ ] Schema normalized appropriately
+- [ ] Indexes on query fields
+- [ ] Foreign keys and constraints
+- [ ] Migrations reversible
+- [ ] No N+1 queries
+- [ ] Transactions used correctly
+
+## Security Checklist
+- [ ] No plaintext passwords
+- [ ] Input validation
+- [ ] SQL injection prevention
+- [ ] Authorization checks
+- [ ] Rate limiting
+- [ ] Sensitive data not logged
+
+## Common Anti-Patterns
+
+### API Anti-Patterns
+- Inconsistent endpoint naming
+- Wrong HTTP methods or status codes
+- No pagination
+- Missing rate limiting
+- No versioning
+- Not following REST conventions
+
+### Database Anti-Patterns
+- Missing indexes on foreign keys
+- N+1 query problems
+- Not using transactions
+- Missing connection pooling
+- Non-reversible migrations
+- Over-normalization or under-normalization
+
+### Security Anti-Patterns
+- Plaintext passwords
+- SQL injection vulnerabilities
+- Missing authorization checks
+- Logging sensitive data (passwords, tokens, SSNs)
+- No input validation
+- Missing CSRF protection
+
+### Performance Anti-Patterns
+- Synchronous external API calls in request path
+- No caching for expensive operations
+- Not using background jobs
+- Missing query optimization
+- No connection pooling
+- Blocking operations in async code
+
+## Output Template
+
+```markdown
+## Backend Review: {Feature/API}
+
+### API Design
+{Endpoint structure, conventions}
+
+### Data Model
+{Schema design, relationships}
+
+### Database Performance
+{Query optimization, indexes}
+
+### Security
+{Auth patterns, validation}
+
+### Issues
+| Severity | Issue | Location | Fix |
+|----------|-------|----------|-----|
+| {Level} | {Problem} | {File:line} | {Solution} |
+
+### Recommendations
+1. {Priority item}
+2. {Secondary item}
+```
+
+## Key Focus Areas
+
+### API Design
+- RESTful conventions (resources, methods, status codes)
+- GraphQL schema design
+- API versioning strategies
+- Request/response validation
+- Error handling and messaging
+- Pagination and filtering
+- Rate limiting
+
+### Database Patterns
+- Schema design and normalization
+- Indexing strategies
+- Query optimization
+- Transaction management
+- Connection pooling
+- Migration best practices
+- N+1 query prevention
+
+### Data Modeling
+- Entity definition
+- Relationship modeling (1:1, 1:N, N:M)
+- Data types and constraints
+- Validation rules
+- Audit trails
+
+### Authentication & Authorization
+- Password hashing (bcrypt, argon2)
+- JWT or session management
+- OAuth2 / OIDC patterns
+- RBAC (Role-Based Access Control)
+- API key management
+
+### Performance & Scalability
+- Query optimization and EXPLAIN plans
+- Caching strategies (Redis, memcached)
+- Background jobs (Celery, Bull)
+- Database read replicas
+- Horizontal scaling
+
+### Integration Patterns
+- External API resilience (retry, timeout, circuit breaker)
+- Webhook handling with retry
+- Message queue patterns
+- Idempotency for critical operations
+
+## Tools
+
+- OpenAPI/Swagger for API docs
+- EXPLAIN for query plans
+- Database migrations (Alembic, Flyway)
+- APM tools (DataDog, New Relic)
+- Error tracking (Sentry)
+- Load testing (Locust, k6)

package/skills/engineering/backend/refs/patterns.md

@@ -0,0 +1,181 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Backend Code Patterns
+
+## API Endpoint Pattern
+
+```python
+@router.post("/api/v1/orders", status_code=201)
+async def create_order(
+    order: OrderCreate,
+    current_user: User = Depends(get_current_user)
+) -> OrderResponse:
+    # Authorization
+    if not current_user.can_create_orders:
+        raise HTTPException(403, "Insufficient permissions")
+
+    # Validation
+    if order.total < 0:
+        raise HTTPException(400, "Total must be non-negative")
+
+    # Transaction
+    async with db.transaction():
+        db_order = await db.orders.create(**order.dict())
+        await send_notification.delay(db_order.id)
+
+    return OrderResponse.from_orm(db_order)
+```
+
+## Query Optimization Pattern
+
+```python
+# Bad: N+1 problem
+orders = await Order.all()
+for order in orders:
+    order.items = await OrderItem.filter(order_id=order.id)
+
+# Good: Eager loading
+orders = await Order.prefetch_related('items').all()
+```
+
+## Database Patterns
+
+### Transaction Management
+```python
+async with db.transaction():
+    user = await User.create(email=email)
+    await Profile.create(user_id=user.id)
+    await send_welcome_email.delay(user.id)
+```
+
+### Connection Pooling
+```python
+# Configure connection pool
+DATABASE_URL = "postgresql://user:pass@localhost/db"
+database = Database(
+    DATABASE_URL,
+    min_size=5,
+    max_size=20
+)
+```
+
+### Migration Best Practices
+```python
+# Reversible migration
+def upgrade():
+    op.add_column('users', sa.Column('status', sa.String(20)))
+
+def downgrade():
+    op.drop_column('users', 'status')
+```
+
+## Authentication Patterns
+
+### Password Hashing
+```python
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+```
+
+### JWT Token Management
+```python
+from jose import jwt
+from datetime import datetime, timedelta
+
+def create_access_token(user_id: int) -> str:
+    expires = datetime.utcnow() + timedelta(hours=1)
+    payload = {"sub": str(user_id), "exp": expires}
+    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")
+```
+
+## Integration Patterns
+
+### External API Resilience
+```python
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=2, max=10)
+)
+async def fetch_external_data(url: str):
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        return response.json()
+```
+
+### Webhook Handling
+```python
+@router.post("/webhooks/stripe")
+async def handle_stripe_webhook(
+    request: Request,
+    signature: str = Header(None, alias="Stripe-Signature")
+):
+    payload = await request.body()
+
+    # Verify signature
+    verify_webhook_signature(payload, signature)
+
+    # Process idempotently
+    event = json.loads(payload)
+    await process_event_idempotent(event)
+
+    return {"status": "received"}
+```
+
+### Circuit Breaker Pattern
+```python
+from circuitbreaker import circuit
+
+@circuit(failure_threshold=5, recovery_timeout=60)
+async def call_payment_service(order_id: int):
+    # Will open circuit after 5 failures
+    # Closes automatically after 60 seconds
+    return await payment_api.charge(order_id)
+```
+
+## Caching Patterns
+
+### Redis Caching
+```python
+from redis import asyncio as aioredis
+
+async def get_user(user_id: int) -> User:
+    cache_key = f"user:{user_id}"
+
+    # Try cache first
+    cached = await redis.get(cache_key)
+    if cached:
+        return User.parse_raw(cached)
+
+    # Fetch from database
+    user = await User.get(id=user_id)
+
+    # Cache for 5 minutes
+    await redis.setex(cache_key, 300, user.json())
+
+    return user
+```
+
+### Cache Invalidation
+```python
+async def update_user(user_id: int, data: UserUpdate):
+    user = await User.get(id=user_id)
+    await user.update(**data.dict())
+
+    # Invalidate cache
+    await redis.delete(f"user:{user_id}")
+
+    return user
+```

package/skills/engineering/debugging/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: debugging
+description: |
+  Systematic debugging and root cause analysis for investigating errors,
+  diagnosing complex issues, and performance profiling.
+
+  Use when: "debug this error", "why is this failing", "root cause analysis",
+  "fix this bug", "investigate crash", "stack trace", "not working"
+portability: portable
+context: fork
+# TODO #339: When Claude Code supports 'paths' in skill frontmatter for
+# file-context auto-activation, add:
+#   paths: ["**/*.log", "**/error*.ts", "**/error*.py", "**/*debug*"]
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# Debugging Skill
+
+Systematic debugging, root cause analysis, and error investigation.
+
+## Debugging Approach
+
+### 1. Understand the Problem
+- What is expected vs actual behavior?
+- When did it start? Can it be reproduced?
+- What changed recently?
+
+### 2. Gather Evidence
+- Read logs and stack traces
+- Review recent changes
+- Identify patterns
+
+### 3. Form Hypothesis
+- What is the most likely cause?
+- What evidence supports this?
+
+### 4. Test Hypothesis
+- Design targeted test
+- Observe results
+- Refine if needed
+
+### 5. Implement Fix
+- Develop minimal fix
+- Verify resolution
+- Add regression tests
+
+### 6. Document
+- Root cause and fix
+- Add monitoring/alerting
+
+## Issue Categories
+
+- **Logic Errors**: Incorrect conditions, off-by-one, wrong operators
+- **State Errors**: Race conditions, stale closures, shared mutable state
+- **Integration Errors**: API mismatch, auth issues, timeouts
+- **Performance**: N+1 queries, missing indexes, memory leaks
+- **Environment**: Config differences, missing vars, permissions
+
+## Systematic Process
+
+Follow the six-step debugging process with:
+- Checklists for investigation and evidence gathering
+- Severity levels (CRITICAL, HIGH, MEDIUM, LOW)
+- Output templates for documentation
+- Tools by environment (browser, Node.js, database)
+
+See [refs/process.md](refs/process.md) for detailed process, checklists, and severity guidelines.
+
+## Common Patterns
+
+Debugging techniques and solutions for:
+- Null/undefined issues with optional chaining
+- Async timing and race conditions
+- Scope and closure problems
+- Binary search debugging with git bisect
+- Performance profiling
+- Database query analysis
+
+See [refs/patterns.md](refs/patterns.md) for code examples and debugging techniques.
+
+## External Integration Discovery
+
+Debugging can leverage available integrations by capability:
+
+| Capability | Discovery Patterns | Provides |
+|------------|-------------------|----------|
+| **Error tracking** | `sentry`, `rollbar`, `datadog` | Recent errors, stack traces, user context |
+| **Observability** | `newrelic`, `dynatrace`, `telemetry` | APM data, traces, metrics |
+| **Logging** | `splunk`, `elastic`, `cloudwatch` | Log aggregation, search |
+
+Discover available integrations via capability detection. Fall back to local log analysis via wicked-garden:search when none available.
+
+## Notes
+
+- Start with the simplest explanation
+- Use scientific method: hypothesis, test, refine
+- Document your findings for future reference
+- Add tests to prevent regression

package/skills/engineering/debugging/refs/patterns.md

@@ -0,0 +1,248 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Debugging Code Patterns
+
+## Binary Search Debugging
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good v1.2.0
+# Git will checkout commits to test
+# After each test:
+git bisect good  # or git bisect bad
+# Continue until found
+git bisect reset
+```
+
+## Log-Based Debugging
+
+```javascript
+console.log('1. Input:', input);
+console.log('2. Validated:', validated);
+console.log('3. Result:', result);
+```
+
+## Performance Profiling
+
+```javascript
+console.time('operation');
+await expensiveOperation();
+console.timeEnd('operation');
+
+// Or with Performance API
+const start = performance.now();
+await expensiveOperation();
+const duration = performance.now() - start;
+console.log(`Operation took ${duration}ms`);
+```
+
+## Common Error Patterns
+
+### Null/Undefined Issues
+
+```javascript
+// Problem: user.profile.name (profile is null)
+// Fix: Optional chaining
+const name = user?.profile?.name ?? 'Unknown';
+
+// Problem: Cannot read property of undefined
+// Fix: Guard clauses
+if (!user || !user.profile) {
+  return 'Unknown';
+}
+return user.profile.name;
+```
+
+### Async Timing Issues
+
+```javascript
+// Problem: Race condition
+let result;
+fetchData().then(data => result = data);
+console.log(result); // undefined - promise not resolved yet
+
+// Fix: Use await
+const result = await fetchData();
+console.log(result); // correct value
+
+// Problem: Parallel promises with errors
+await Promise.all([promise1, promise2]); // Fails fast
+
+// Fix: Handle all settled
+const results = await Promise.allSettled([promise1, promise2]);
+results.forEach((result, i) => {
+  if (result.status === 'rejected') {
+    console.error(`Promise ${i} failed:`, result.reason);
+  }
+});
+```
+
+### Scope/Closure Issues
+
+```javascript
+// Problem: var in loop
+for (var i = 0; i < 3; i++) {
+  setTimeout(() => console.log(i), 100); // Logs: 3,3,3
+}
+
+// Fix: Use let (block scope)
+for (let i = 0; i < 3; i++) {
+  setTimeout(() => console.log(i), 100); // Logs: 0,1,2
+}
+
+// Problem: Stale closure
+function createCounter() {
+  let count = 0;
+  return {
+    increment: () => count++,
+    getCount: () => count
+  };
+}
+
+// Fix: Use current state, not captured
+function useCounter() {
+  const [count, setCount] = useState(0);
+  const increment = useCallback(() => {
+    setCount(c => c + 1); // Use function updater
+  }, []);
+}
+```
+
+### Race Conditions
+
+```javascript
+// Problem: Lost updates
+let count = 0;
+async function increment() {
+  const current = count;
+  await delay(10);
+  count = current + 1; // Multiple calls overwrite each other
+}
+
+// Fix: Atomic operations
+async function increment() {
+  count++; // Or use locks/transactions for complex cases
+}
+
+// Problem: Multiple async setState
+const [data, setData] = useState([]);
+setData(data.concat(newItem)); // Bad: uses stale data
+
+// Fix: Functional update
+setData(prev => prev.concat(newItem));
+```
+
+## Debugging Techniques
+
+### Stack Trace Analysis
+
+```
+Error: Cannot read property 'id' of undefined
+    at processUser (app.js:42:15)       <- Where it failed
+    at handleRequest (app.js:28:10)     <- What called it
+    at Server.<anonymous> (app.js:10:5) <- Origin
+```
+
+Work backwards:
+1. Line 42: `user.id` - user is undefined
+2. Line 28: Called processUser without validating user
+3. Line 10: Request handler didn't check if user exists
+
+### Breakpoint Debugging
+
+```javascript
+// Add debugger statement
+function complexFunction(data) {
+  debugger; // Execution pauses here in DevTools
+  const processed = processData(data);
+  return processed;
+}
+```
+
+### Conditional Logging
+
+```javascript
+const DEBUG = process.env.NODE_ENV === 'development';
+
+function log(...args) {
+  if (DEBUG) {
+    console.log('[DEBUG]', ...args);
+  }
+}
+
+log('User state:', user); // Only in development
+```
+
+### Network Debugging
+
+```javascript
+// Add request/response logging
+fetch(url)
+  .then(response => {
+    console.log('Response status:', response.status);
+    console.log('Response headers:', response.headers);
+    return response.json();
+  })
+  .then(data => {
+    console.log('Response data:', data);
+    return data;
+  })
+  .catch(error => {
+    console.error('Fetch failed:', error);
+    console.error('URL:', url);
+  });
+```
+
+## Database Debugging
+
+### Query Analysis
+
+```sql
+-- Check query execution plan
+EXPLAIN ANALYZE
+SELECT * FROM orders
+WHERE user_id = 123
+AND created_at > '2024-01-01';
+
+-- Look for:
+-- - Sequential scans (add index)
+-- - High cost estimates
+-- - Missing indexes
+```
+
+### N+1 Query Detection
+
+```javascript
+// Problem: N+1 queries
+const users = await User.findAll();
+for (const user of users) {
+  const orders = await Order.findAll({ where: { userId: user.id } });
+  user.orders = orders;
+}
+
+// Fix: Eager loading
+const users = await User.findAll({
+  include: [{ model: Order }]
+});
+```
+
+## Memory Leak Debugging
+
+```javascript
+// Problem: Event listener not removed
+component.addEventListener('click', handler);
+// Component destroyed but listener remains
+
+// Fix: Cleanup
+useEffect(() => {
+  const handler = () => { /* ... */ };
+  component.addEventListener('click', handler);
+
+  return () => {
+    component.removeEventListener('click', handler);
+  };
+}, []);
+```