ai-sprint-kit 1.1.0

package/templates/.claude/commands/debug.md

@@ -0,0 +1,449 @@
+---
+description: Investigate and fix bugs with root cause analysis
+argument-hint: [bug description or error message]
+---
+
+## Command: /debug
+
+Systematically investigate bugs, perform root cause analysis, and provide fixes with regression tests.
+
+## Usage
+
+```
+/debug "users can't login"
+/debug "500 error on checkout"
+/debug "memory leak in WebSocket handler"
+/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/debug-{timestamp}-{slug}.md`
+
+## Debug Report
+
+Save to: `ai_context/reports/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
+
+**/debug** → **/test**
+- After fixing bug, add regression test
+
+**/debug** → **/review**
+- Review fix for quality and security
+
+**/debug** → **/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."**