ai-sprint-kit 1.3.0 → 2.0.0

package/templates/.claude/commands/ai-sprint-debug.md

@@ -1,453 +0,0 @@
----
-description: Investigate and fix bugs with root cause analysis
-argument-hint: [bug description or error message]
----
-
-**THINK HARDER** - Systematic root cause analysis requires careful investigation.
-
-**Objective:** $ARGUMENTS
-
-## Command: /ai-sprint-debug
-
-Systematically investigate bugs, perform root cause analysis, and provide fixes with regression tests.
-
-## Usage
-
-```
-/ai-sprint-debug "users can't login"
-/ai-sprint-debug "500 error on checkout"
-/ai-sprint-debug "memory leak in WebSocket handler"
-/ai-sprint-debug "database query is slow"
-```
-
-## Workflow
-
-### 0. Initialize Context
-- Get timestamp: `date "+%y%m%d-%H%M"` (DO NOT guess dates)
-- Check `ai_context/memory/learning.md` for known bug patterns
-
-### 1. Understand the Problem
-- What's the expected behavior?
-- What's the actual behavior?
-- When did it start?
-- Can it be reproduced?
-- Any error messages/stack traces?
-
-### 2. Reproduce the Bug
-- Find minimal reproduction steps
-- Document exact conditions
-- Identify patterns (timing, data, environment)
-
-### 3. Investigate Root Cause
-- Analyze error messages
-- Check logs (app, server, database)
-- Review recent changes
-- Use debugging tools
-
-### 4. Fix the Bug
-- Implement minimal fix
-- Test thoroughly
-- Add regression test
-- Document the fix
-
-## Debugging Process
-
-### Phase 1: Gather Information
-```markdown
-## Bug Report
-
-**Error:** "Cannot read property 'name' of undefined"
-
-**Expected:** User profile displays name
-**Actual:** Application crashes
-
-**Reproduction:**
-1. Go to /profile
-2. Click "Edit Profile"
-3. Error occurs
-
-**Stack Trace:**
-```
-Error: Cannot read property 'name' of undefined
-    at ProfilePage (app/profile/page.tsx:45)
-    at renderComponent (react.js:123)
-```
-
-**Logs:**
-```
-[ERROR] User data undefined for ID: user_123
-[DEBUG] Database query returned null
-```
-```
-
-### Phase 2: Analyze Root Cause
-```typescript
-// Bug location: app/profile/page.tsx:45
-function ProfilePage() {
-  const user = await getUser(userId);
-  return <div>{user.name}</div>; // ← Crashes here if user is null
-}
-```
-
-**Root Cause:** No null check after database query.
-
-### Phase 3: Implement Fix
-```typescript
-// Fixed version
-async function ProfilePage() {
-  const user = await getUser(userId);
-
-  if (!user) {
-    throw new NotFoundError('User not found');
-  }
-
-  return <div>{user.name}</div>;
-}
-```
-
-### Phase 4: Add Regression Test
-```typescript
-test('handles missing user gracefully', async () => {
-  const response = await request(app)
-    .get('/profile/invalid-user-id');
-
-  expect(response.status).toBe(404);
-  expect(response.body.error).toContain('User not found');
-});
-```
-
-## Common Bug Patterns
-
-### 1. Null/Undefined Errors
-```typescript
-// Bug
-function getUser(id) {
-  const user = users.find(u => u.id === id);
-  return user.name; // Error if user is undefined
-}
-
-// Fix
-function getUser(id) {
-  const user = users.find(u => u.id === id);
-  if (!user) {
-    throw new NotFoundError(`User ${id} not found`);
-  }
-  return user.name;
-}
-```
-
-### 2. Race Conditions
-```typescript
-// Bug
-let count = 0;
-async function increment() {
-  const current = count;
-  await delay(10);
-  count = current + 1; // Race condition
-}
-
-// Fix (use atomic operations)
-let count = 0;
-const lock = new AsyncLock();
-
-async function increment() {
-  await lock.acquire('count', async () => {
-    count++;
-  });
-}
-```
-
-### 3. Memory Leaks
-```typescript
-// Bug - event listener not removed
-class Component {
-  constructor() {
-    window.addEventListener('resize', this.handleResize);
-  }
-}
-
-// Fix - cleanup in destructor
-class Component {
-  constructor() {
-    this.handleResize = this.handleResize.bind(this);
-    window.addEventListener('resize', this.handleResize);
-  }
-
-  destroy() {
-    window.removeEventListener('resize', this.handleResize);
-  }
-}
-```
-
-### 4. Type Errors
-```typescript
-// Bug - type coercion
-function add(a, b) {
-  return a + b;
-}
-
-add("10", 20); // "1020" (string concatenation)
-
-// Fix - proper types
-function add(a: number, b: number): number {
-  return Number(a) + Number(b);
-}
-```
-
-### 5. SQL N+1 Queries
-```typescript
-// Bug - N+1 queries
-const posts = await db.posts.findMany();
-for (const post of posts) {
-  post.author = await db.users.findUnique({ where: { id: post.authorId } });
-}
-
-// Fix - single query with join
-const posts = await db.posts.findMany({
-  include: { author: true }
-});
-```
-
-## Debugging Tools
-
-### Console Logging
-```typescript
-// Strategic logging
-console.log('Before API call:', { userId, timestamp: Date.now() });
-const user = await fetchUser(userId);
-console.log('After API call:', { user, timestamp: Date.now() });
-```
-
-### Debugger Breakpoints
-```typescript
-function calculateTotal(items) {
-  debugger; // Pauses execution here
-  return items.reduce((sum, item) => sum + item.price, 0);
-}
-```
-
-### Stack Trace Analysis
-```
-Error: Cannot read property 'name' of undefined
-    at getUser (app.js:45:12)        ← Problem here
-    at handleRequest (server.js:89:5) ← Called from here
-```
-
-### Log Analysis
-```bash
-# Find errors
-grep "ERROR" app.log
-
-# Count error types
-grep "ERROR" app.log | sort | uniq -c
-
-# Track specific user
-grep "userId:12345" app.log
-```
-
-## Memory Integration
-
-Before debugging:
-- Check `ai_context/memory/learning.md` for past bug patterns
-
-After debugging:
-- Update `ai_context/memory/learning.md` with new bug pattern
-- Save report to `ai_context/reports/ai-sprint-debug-{timestamp}-{slug}.md`
-
-## Debug Report
-
-Save to: `ai_context/reports/ai-sprint-debug-YYMMDD-slug.md`
-
-```markdown
-# Bug Fix Report
-
-**Date:** {use bash: date "+%Y-%m-%d"}
-**Bug:** Users unable to login
-**Severity:** Critical
-**Status:** Fixed
-
-## Problem
-
-**Expected:** User logs in with valid credentials
-**Actual:** Login fails with "Invalid token" error
-
-**Reproduction:**
-1. Go to /login
-2. Enter email: test@example.com
-3. Enter password: correct-password
-4. Error: "Invalid token"
-
-## Investigation
-
-**Stack Trace:**
-```
-Error: Invalid token
-    at validateToken (auth.ts:45)
-    at loginUser (api/auth.ts:23)
-```
-
-**Logs:**
-```
-[ERROR] Token verification failed: jwt malformed
-[DEBUG] Token received: undefined
-```
-
-**Root Cause:**
-JWT token generated but not included in API response.
-
-## Fix
-
-```typescript
-// Before (bug)
-const token = generateJWT(user);
-return { user }; // Token not returned!
-
-// After (fixed)
-const token = generateJWT(user);
-return { user, token };
-```
-
-## Verification
-
-- ✅ Login now works
-- ✅ Token present in response
-- ✅ No regressions
-- ✅ Regression test added
-
-## Regression Test
-
-```typescript
-test('login returns JWT token', async () => {
-  const response = await request(app)
-    .post('/api/auth/login')
-    .send({ email: 'test@example.com', password: 'password' });
-
-  expect(response.body).toHaveProperty('token');
-  expect(response.body.token).toMatch(/^eyJ/);
-});
-```
-
-## Prevention
-
-Added similar fix to `/api/auth/register`.
-Updated docs to always return auth tokens.
-```
-
-## Performance Debugging
-
-### Slow Queries
-```sql
--- Find slow queries (PostgreSQL)
-SELECT query, calls, mean_time
-FROM pg_stat_statements
-WHERE mean_time > 100
-ORDER BY mean_time DESC;
-
--- Check for missing indexes
-EXPLAIN ANALYZE
-SELECT * FROM users WHERE email = 'test@example.com';
-```
-
-### Memory Profiling
-```javascript
-// Node.js heap snapshot
-const v8 = require('v8');
-v8.writeHeapSnapshot('./heap-snapshot.heapsnapshot');
-```
-
-### Performance Timing
-```typescript
-console.time('operation');
-await expensiveOperation();
-console.timeEnd('operation'); // operation: 1234ms
-```
-
-## Git Bisect (Find When Bug Was Introduced)
-```bash
-git bisect start
-git bisect bad              # Current commit has bug
-git bisect good v1.2.0      # v1.2.0 was working
-# Git checks out middle commit
-npm test                    # Test if bug exists
-git bisect good # or bad
-# Repeat until bug commit found
-git bisect reset
-```
-
-## Integration with Other Commands
-
-**/ai-sprint-debug** → **/ai-sprint-test**
-- After fixing bug, add regression test
-
-**/ai-sprint-debug** → **/ai-sprint-review**
-- Review fix for quality and security
-
-**/ai-sprint-debug** → **/ai-sprint-secure**
-- If security bug, run security scan
-
-## Debug Checklist
-
-### Investigation
-- ✅ Read full error message
-- ✅ Analyze stack trace
-- ✅ Reproduce reliably
-- ✅ Check recent changes
-- ✅ Search error online
-
-### Fix
-- ✅ Minimal change (don't refactor while debugging)
-- ✅ Test thoroughly
-- ✅ No new bugs introduced
-- ✅ Edge cases handled
-
-### Prevention
-- ✅ Regression test added
-- ✅ Root cause documented
-- ✅ Similar bugs prevented
-- ✅ Team notified
-
-## Common Debugging Strategies
-
-### Binary Search
-```typescript
-// Bug somewhere in 1000-line function
-// Add logs to narrow down
-function complexFunction() {
-  console.log('Step 1 OK'); // Works
-  // ... 500 lines ...
-  console.log('Step 2 OK'); // Works
-  // ... 500 lines ...
-  console.log('Step 3 OK'); // Doesn't print → bug before this
-}
-```
-
-### Rubber Duck Debugging
-1. Explain code line-by-line
-2. Often find bug while explaining
-3. Write it down or talk to AI
-
-### Divide and Conquer
-1. Disable half the code
-2. See if bug still occurs
-3. Narrow down to problematic section
-
-## Success Criteria
-
-Debugging is successful when:
-- ✅ Root cause identified
-- ✅ Bug fixed (not masked)
-- ✅ Fix verified with tests
-- ✅ Regression test prevents recurrence
-- ✅ No new bugs introduced
-- ✅ Documented for future
-
-## Remember
-
-**Good debugging:**
-- Understands problem fully before fixing
-- Makes minimal changes
-- Tests thoroughly
-- Prevents recurrence
-- Documents findings
-
-**"Hours of debugging can save minutes of planning."**