Error Debugger

Error Debugger

Purpose

Context-aware debugging that learns from past solutions. When an error occurs: 1. Searches memory for similar past errors 2. Analyzes error message and stack trace 3. Provides immediate fix with code examples 4. Creates regression test via testing-builder 5. Saves solution to memory for future

For ADHD users: Eliminates debugging frustration - instant, actionable fixes. For SDAM users: Recalls past solutions you've already found. For all users: Gets smarter over time as it learns from your codebase.

Activation Triggers

• User says: "debug this", "fix this error", "why is this failing"
• Error messages containing: TypeError, ReferenceError, SyntaxError, ECONNREFUSED, CORS, 404, 500, etc.
• Stack traces pasted into conversation
• "Something's broken" or similar expressions

Core Workflow

1. Parse Error

Extract key information:

{
  error_type: "TypeError|ReferenceError|ECONNREFUSED|...",
  message: "Cannot read property 'map' of undefined",
  stack_trace: [...],
  file: "src/components/UserList.jsx",
  line: 42,
  context: "Rendering user list"
}

2. Search Past Solutions

Query context-manager:

search memories for:
- error_type match
- similar message (fuzzy match)
- same file/component if available
- related tags (if previously tagged)

If match found:

🔍 Found similar past error!

📝 3 months ago: TypeError in UserList component
✅ Solution: Added null check before map
⏱️ Fixed in: 5 minutes
🔗 Memory: procedures/{uuid}.md

Applying the same solution...

If no match:

🆕 New error - analyzing...
(Will save solution after fix)

3. Analyze Error

See reference.md for comprehensive error pattern library.

Quick common patterns:

• TypeError: Cannot read property 'X' of undefined → Optional chaining + defaults
• ECONNREFUSED → Check service running, verify ports
• CORS errors → Configure CORS headers
• 404 Not Found → Verify route definition
• 500 Internal Server Error → Check server logs

4. Provide Fix

Format:

🔧 Error Analysis

**Type**: {error_type}
**Location**: {file}:{line}
**Cause**: {root_cause_explanation}

**Fix**:

// ❌ Current code const users = data.users; return users.map(user => <div>{user.name}</div>);

// ✅ Fixed code const users = data?.users || []; return users.map(user => <div>{user.name}</div>);

**Explanation**: Added optional chaining and default empty array to handle case where data or data.users is undefined.

**Prevention**: Always validate API response structure before using.

**Next steps**:
1. Apply the fix
2. Test manually
3. I'll create a regression test

5. Save Solution

After fix confirmed working:

# Save to context-manager as PROCEDURE
remember: Fix for TypeError in map operations
Type: PROCEDURE
Tags: error, typescript, array-operations
Content: When getting "Cannot read property 'map' of undefined",
         add optional chaining and default empty array:
         data?.users || []

Memory structure:

# PROCEDURE: Fix TypeError in map operations

**Error Type**: TypeError
**Message Pattern**: Cannot read property 'map' of undefined
**Context**: Array operations on potentially undefined data

## Solution

Use optional chaining and default values:

// Before const items = data.items; return items.map(...)

// After const items = data?.items || []; return items.map(...)

## When to Apply

- API responses that might be undefined
- Props that might not be passed
- Array operations on uncertain data

## Tested

✅ Fixed in UserList component (2025-10-17)
✅ Regression test: tests/components/UserList.test.jsx

## Tags

error, typescript, array-operations, undefined-handling

6. Create Regression Test

Automatically invoke testing-builder:

create regression test for this fix:
- Test that component handles undefined data
- Test that component handles empty array
- Test that component works with valid data

Tool Persistence Pattern (Meta-Learning)

Critical principle from self-analysis: Never give up on first obstacle. Try 3 approaches before abandoning a solution path.

Debugging Tools Hierarchy

When debugging an error, try these tools in sequence:

1. Search Past Solutions (context-manager)

# First approach: Check memory
search memories for error pattern

If no past solution found → Continue to next approach

2. GitHub Copilot CLI Search

# Second approach: Search public issues
copilot "Search GitHub for solutions to: $ERROR_MESSAGE"

If Copilot doesn't find good results → Continue to next approach

3. Web Search with Current Context

# Third approach: Real-time web search
[Use web search for latest Stack Overflow solutions]

If web search fails → Then ask user for more context

Real Example from Meta-Analysis

What happened: Tried GitHub MCP → Got auth error → Immediately gave up

What should have happened: 1. Try GitHub MCP → Auth error 2. Try gh CLI → Check if authenticated 3. Try direct GitHub API → Use personal token 4. Then create manual instructions if all fail

Outcome: The gh CLI WAS authenticated and worked perfectly. We gave up too early.

Applying This to Error Debugging

When fixing an error:

// Pattern: Try 3 fix approaches
async function debugError(error) {
  // Approach 1: Past solution
  const pastFix = await searchMemories(error);
  if (pastFix?.success_rate > 80%) {
    return applyPastFix(pastFix);
  }

  // Approach 2: Pattern matching
  const commonFix = matchErrorPattern(error);
  if (commonFix) {
    return applyCommonFix(commonFix);
  }

  // Approach 3: External search (Copilot/Web)
  const externalSolution = await searchExternalSolutions(error);
  if (externalSolution) {
    return applyExternalSolution(externalSolution);
  }

  // Only NOW ask for more context
  return askUserForMoreContext(error);
}

Integration Tool Persistence

When integrations are available, use them in this order:

For Error Search: 1. GitHub Copilot CLI → Search issues in your repos and similar projects 2. Local memory → Past solutions you've saved 3. Web search → Latest Stack Overflow/docs

For Solutions: 1. Past solution from memory (fastest) 2. Codegen-ai agent (if complex bug) → Automated PR 3. Jules CLI async task (if time-consuming fix) 4. Manual fix with code examples

Metrics

Track debugging approach success:

{
  "error_id": "uuid",
  "approaches_tried": [
    {"type": "memory_search", "result": "no_match"},
    {"type": "copilot_search", "result": "success", "time": "5s"},
    {"type": "applied_fix", "verified": true}
  ],
  "total_time": "30s",
  "lesson": "Copilot found solution on second try"
}

Key insight: Most "failed" approaches are actually "didn't try enough" approaches.

Context Integration

Query Past Solutions

Before analyzing new error:

// Search context-manager
const pastSolutions = searchMemories({
  type: 'PROCEDURE',
  tags: [errorType, language, framework],
  content: errorMessage,
  fuzzyMatch: true
});

if (pastSolutions.length > 0) {
  // Show user the past solution
  // Ask if they want to apply it
  // If yes, apply and test
  // If no, analyze fresh
}

Learning Over Time

Track which solutions work:

{
  solution_id: "uuid",
  error_pattern: "TypeError.*map.*undefined",
  times_applied: 5,
  success_rate: 100%,
  last_used: "2025-10-15",
  avg_fix_time: "2 minutes"
}

Sort solutions by success rate when multiple matches found.

Project-Specific Patterns

Some errors are project-specific:

// BOOSTBOX-specific
Error: "Boost ID not found"
→ Solution: Check boost exists before processing

// Tool Hub-specific
Error: "Tool not installed"
→ Solution: Run tool installer first

// Save these as PROJECT-specific procedures

Integration with Other Skills

Testing Builder

After providing fix:

Automatically invoke: testing-builder
Create regression test for: {error_scenario}
Ensure test fails without fix, passes with fix

Context Manager

Query for similar errors:

search memories for:
- PROCEDURE type
- Error tag
- Similar message
- Same file/component

Save new solutions:

Save as PROCEDURE:
- Error pattern
- Solution
- Code examples
- Tested timestamp

Rapid Prototyper

For complex fixes:

If fix requires significant refactoring:
→ Invoke rapid-prototyper
→ Create isolated example showing fix
→ User validates before applying to codebase

Additional Resources

• [Error Pattern Library](reference.md) - Comprehensive patterns for JavaScript, Network, Database, React errors
• [Debugging Examples](examples.md) - Step-by-step debugging workflow examples

Quick Reference

Common Error Patterns

Trigger Phrases

• "debug this"
• "fix this error"
• "why is this failing"
• "something's broken"
• [paste error message]
• [paste stack trace]

File Locations

• Past solutions: ~/.claude-memories/procedures/ (Linux/macOS) or %USERPROFILE%\.claude-memories\procedures\ (Windows)
• Error patterns: Tagged with "error" in memory index

Success Criteria

✅ Common errors fixed instantly (<30 seconds) ✅ Past solutions automatically recalled ✅ All fixes include code examples ✅ Regression tests created automatically ✅ Solutions saved for future reference ✅ Debugging gets faster over time

Debugging Workflow Examples

Step-by-step debugging scenarios showing the error-debugger skill in action.

Example 1: Simple TypeError

Scenario

User is getting a TypeError when rendering a user list component.

---

User: "Getting error: Cannot read property 'map' of undefined"

Debugger:

🔍 Searching past solutions...
✅ Found solution from 2 weeks ago!

This is a common pattern in your codebase. You've fixed this 3 times before:

**Solution**: Add optional chaining and default array

const items = data?.items || []; return items.map(item => ...)

Apply this fix? (yes/no)

User: "yes"

Debugger:

✅ Fix applied
🧪 Creating regression test...
📝 Solution saved to memory

**Regression test**: tests/components/ItemList.test.jsx

The test verifies:
- Component handles undefined data gracefully
- Component handles empty array
- Component works with valid data

Test output:
✅ renders with undefined data
✅ renders with empty array
✅ renders with valid user data

Key Takeaways

• Past solution was found instantly (< 2 seconds)
• User confirmed application without needing explanation
• Regression test auto-generated prevents future occurrences
• Solution saved for next time it happens

---

Example 2: New Error Pattern

Scenario

User encounters a DNS resolution error for the first time.

---

User: "Error: ENOTFOUND api.example.com"

Debugger:

🆕 New error pattern

**Type**: DNS resolution failure
**Error Code**: ENOTFOUND
**Cause**: Cannot resolve hostname api.example.com

**Possible causes**:
1. Typo in hostname
2. Service is down
3. Network connectivity issue
4. DNS server problem

**Troubleshooting steps**:
1. Check hostname spelling in your code
2. Ping the hostname: `ping api.example.com`
3. Check if service is accessible: `curl -I https://api.example.com`
4. Verify network: `ping 8.8.8.8`

What's the result of these checks?

User: "typo - should be api.myapp.com"

Debugger:

✅ Root cause identified: Hostname typo

**Location**: Let me search your codebase for "api.example.com"...

Found in:
- src/config/api.js:5
- .env.example:2

**Fix**: Update API endpoint

// ❌ Wrong (src/config/api.js:5) const API_URL = 'https://api.example.com';

// ✅ Correct const API_URL = 'https://api.myapp.com';

❌ Wrong (.env.example:2)

API_URL=https://api.example.com

✅ Correct

API_URL=https://api.myapp.com

Would you like me to apply these changes?

User: "yes"

Debugger:

✅ Changes applied to 2 files

💾 Saving solution to memory...

**Memory saved**: PROCEDURE - Fix DNS ENOTFOUND errors
Tags: error, network, dns, api

🧪 Creating test to verify API endpoint...

**Test created**: tests/api/connection.test.js

describe('API Connection', () => { it('uses correct API endpoint', () => { expect(API_URL).toBe('https://api.myapp.com'); expect(API_URL).not.toContain('example.com'); });

it('can resolve API hostname', async () => { const url = new URL(API_URL); // Verify hostname is resolvable await expect(fetch(API_URL, { method: 'HEAD' })).resolves.toBeDefined(); }); });

**Next time** you get ENOTFOUND, I'll remember to check for typos first!

Key Takeaways

• Unknown error → systematic troubleshooting
• User provided key info (typo)
• Multiple files updated at once
• Test prevents hostname typos in future
• Solution saved for pattern recognition

---

Example 3: Complex Server Error

Scenario

User getting 500 error from API endpoint, needs deeper investigation.

---

User: "Getting 500 error from /api/users endpoint"

Debugger:

🔍 500 Internal Server Error - need more information

**What I need**:
1. Server logs (most recent error)
2. Request payload
3. Database connection status

500 errors are server-side, so I need to see what's happening on the backend.

Can you provide server logs?

User: [pastes logs]

Error: syntax error at or near "name"
  at Connection.parseE (/app/node_modules/pg/lib/connection.js:614:13)
  at Connection.parseMessage (/app/node_modules/pg/lib/connection.js:413:19)
Query: SELECT id name email FROM users WHERE active = true

Debugger:

✅ Found root cause: SQL syntax error in query

**Error**: Invalid SQL syntax - missing commas in column list
**Location**: Based on stack trace, checking src/api/users.js...

Found the issue at src/api/users.js:42:

// ❌ Current (line 42) const query = SELECT id name email FROM users WHERE active = true ;

**Problem**: Missing commas between column names in SELECT statement

**Fix**:

// ✅ Corrected const query = SELECT id, name, email FROM users WHERE active = true ;

**Prevention**: This is a common error with raw SQL queries.

**Recommendations**:
1. Use a query builder (knex.js) or ORM (Prisma, TypeORM)
2. If using raw SQL, use parameterized queries
3. Add SQL linting to your editor

Would you like me to:
a) Apply the fix now
b) Refactor to use a query builder
c) Both

User: "c - both"

Debugger:

✅ Excellent choice! This will prevent future SQL syntax errors.

**Step 1**: Applying immediate fix to src/api/users.js:42
✅ Done

**Step 2**: Refactoring to use query builder

I'll use Prisma since it's type-safe and prevents SQL injection.

First, let me check if Prisma is already installed...
Found package.json but no Prisma dependency.

**Installation needed**:

npm install @prisma/client npm install --save-dev prisma

**Setting up Prisma**:

npx prisma init

**Refactored code** (src/api/users.js):

// ❌ Old way const { rows } = await db.query( SELECT id, name, email FROM users WHERE active = true );

// ✅ New way with Prisma const users = await prisma.user.findMany({ where: { active: true }, select: { id: true, name: true, email: true } });

**Benefits**:
- ✅ Type safety (compile-time error checking)
- ✅ No SQL injection vulnerabilities
- ✅ Auto-completion in your editor
- ✅ Automatic migrations
- ✅ No syntax errors

Would you like me to:
1. Create the Prisma schema
2. Set up the migration
3. Refactor all your SQL queries to Prisma

User: "yes, all of it"

Debugger:

🚀 Refactoring to Prisma...

**Created**: prisma/schema.prisma
**Migrated**: 5 database tables
**Refactored**: 12 SQL queries across 4 files

💾 Saving comprehensive solution to memory...

**Memory saved**: PROCEDURE - Migrating raw SQL to Prisma ORM
Tags: database, sql, prisma, refactoring, best-practices

🧪 Creating integration tests...

**Test created**: tests/api/users.integration.test.js
- Tests user retrieval
- Tests data integrity
- Tests error handling

**Summary**:
✅ Immediate fix applied
✅ Long-term solution implemented
✅ 12 SQL queries refactored
✅ Type safety added
✅ Tests created

**Time saved in future**: ~2 hours (preventing similar errors)

This refactoring prevents an entire class of errors:
- SQL syntax errors
- SQL injection vulnerabilities
- Type mismatches
- Missing migrations

Key Takeaways

• Complex error required systematic investigation
• Debugger asked for specific information (logs)
• Immediate fix + long-term solution offered
• User chose comprehensive approach
• Complete refactoring with migration
• Future errors prevented at architectural level

---

Example 4: Using Tool Persistence Pattern

Scenario

Error occurs where multiple debugging approaches are needed.

---

User: "Getting auth error when pushing to GitHub"

Debugger:

🔍 Authentication error with GitHub

Following tool persistence pattern - trying 3 approaches:

**Approach 1**: Checking local Git credentials...

git config user.name
git config user.email

✅ Git credentials configured:
- Name: toowiredd
- Email: lewistys420@gmail.com

**Approach 2**: Checking GitHub CLI authentication...

gh auth status

✅ GitHub CLI is authenticated!
- Logged in to github.com as toowiredd
- Token: gho_**** (valid)
- Protocol: https

**Approach 3**: Not needed - found the solution!

**Root cause**: You're using HTTPS but might need SSH, or token expired.

Since `gh` CLI is authenticated, let's use it instead:

Instead of manual git push

gh repo view # Verify repo access git push origin main # This should work now

If still getting errors, try:

gh auth refresh # Refresh token

✅ This follows our "try 3 approaches" principle.
❌ OLD me would have given up after the first git config check.
✅ NEW me persisted and found `gh` CLI works!

Key Takeaways

• Multiple approaches tried systematically
• Each approach provided useful information
• Solution found on second approach
• Meta-learning principle applied successfully
• Explicit acknowledgment of improvement from past mistakes

---

Pattern Recognition

After these examples, the error-debugger has learned:

Future behaviors:

• Similar TypeErrors → instant fix (80%+ success rate remembered)
• DNS errors → check for typos first
• SQL errors → suggest ORM migration
• Auth errors → try 3 tools before giving up

See main SKILL.md for complete debugging workflow. See reference.md for error pattern library.

Error Pattern Library

Comprehensive error patterns and solutions for common programming errors.

JavaScript/TypeScript Errors

Cannot read property 'X' of undefined

Pattern: TypeError: Cannot read property 'X' of undefined

Root Cause: Trying to access property on undefined/null object

Common In: API responses, component props, array operations

Fix:

// ❌ Don't
const value = obj.nested.property;

// ✅ Do
const value = obj?.nested?.property || defaultValue;

Prevention: Always validate data structure before accessing

---

X is not a function

Pattern: TypeError: X is not a function

Root Cause: Variable is not a function or function doesn't exist

Common In: Callbacks, async operations, event handlers

Fix:

// ❌ Don't
callback();

// ✅ Do
if (typeof callback === 'function') {
  callback();
}

Prevention: Validate function exists before calling

---

Cannot find module 'X'

Pattern: Error: Cannot find module 'X'

Root Cause: Missing dependency or wrong import path

Common In: Import statements, require calls

Fix:

# Install missing dependency
npm install X

# Or fix import path
import X from './correct/path/to/X';

Prevention: Check package.json for dependencies, verify import paths

---

Network Errors

ECONNREFUSED

Pattern: Error: connect ECONNREFUSED 127.0.0.1:PORT

Root Cause: Service not running or wrong port

Common In: Database connections, API calls, microservices

Fix:

# Check service is running
docker ps  # or
ps aux | grep service-name

# Verify port matches
echo $PORT  # check environment variable

# Restart service if needed
docker restart service-name

Prevention: Use environment variables for ports, add health checks

---

CORS error

Pattern: Access to fetch at 'X' from origin 'Y' has been blocked by CORS policy

Root Cause: Cross-origin request blocked by browser

Common In: Frontend calling backend API

Fix:

// Fix: Configure CORS (Express example)
const cors = require('cors');
app.use(cors({
  origin: ['http://localhost:3000'],
  credentials: true
}));

// Or use proxy in development
// package.json
{
  "proxy": "http://localhost:5000"
}

Prevention: Configure CORS early in development, whitelist origins

---

Timeout errors

Pattern: Error: Timeout of Xms exceeded

Root Cause: Operation takes longer than allowed time

Common In: API calls, database queries, file operations

Fix:

// ❌ Don't use default timeout
const response = await fetch(url);

// ✅ Increase timeout or add retry
const response = await fetch(url, {
  signal: AbortSignal.timeout(30000)  // 30 seconds
});

// Or add retry logic
const fetchWithRetry = async (url, retries = 3) => {
  for (let i = 0; i < retries; i++) {
    try {
      return await fetch(url, { signal: AbortSignal.timeout(10000) });
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
    }
  }
};

Prevention: Set appropriate timeouts, implement retry logic, optimize slow operations

---

Database Errors

Connection refused

Pattern: Error: Connection refused or ECONNREFUSED

Root Cause: Database not running or wrong credentials

Common In: Database connections on app startup

Fix:

# Check database running
docker ps | grep postgres  # or mysql, mongodb, etc.

# Verify connection string
echo $DATABASE_URL

# Check credentials
psql -U username -d database  # for PostgreSQL

# Restart database if needed
docker restart database-container

Prevention: Use health checks, validate connection on startup, use connection pooling

---

Syntax error in query

Pattern: SQL syntax error at or near "X"

Root Cause: Invalid SQL syntax

Common In: Raw SQL queries, string concatenation

Fix:

// ❌ Don't use string concatenation
db.query(`SELECT * FROM users WHERE id = ${id}`);

// ✅ Use parameterized queries
db.query('SELECT * FROM users WHERE id = $1', [id]);

// Or use query builder
db('users').where({ id }).first();

// Or use ORM
await User.findOne({ where: { id } });

Prevention: Always use parameterized queries or ORM, never concatenate user input

---

Unique constraint violation

Pattern: duplicate key value violates unique constraint "X"

Root Cause: Attempting to insert duplicate value in unique field

Common In: User registration, data import

Fix:

// Check before insert
const existing = await db.users.findOne({ where: { email } });
if (existing) {
  throw new Error('Email already exists');
}
await db.users.create({ email });

// Or handle error
try {
  await db.users.create({ email });
} catch (error) {
  if (error.code === '23505') {  // PostgreSQL unique violation
    throw new Error('Email already exists');
  }
  throw error;
}

Prevention: Check for existence before insert, use upsert operations, handle constraint errors

---

React Errors

Too many re-renders

Pattern: Error: Too many re-renders. React limits the number of renders to prevent an infinite loop.

Root Cause: State update in render causing infinite loop

Common In: Event handlers, useEffect dependencies

Fix:

// ❌ Don't set state in render
function Component() {
  const [count, setCount] = useState(0);
  setCount(count + 1);  // Infinite loop!
  return <div>{count}</div>;
}

// ✅ Use callbacks with stable references
function Component() {
  const [count, setCount] = useState(0);
  const handleClick = useCallback(() => {
    setCount(c => c + 1);
  }, []);  // Stable reference
  return <button onClick={handleClick}>{count}</button>;
}

Prevention: Never call setState in render, use useCallback for handlers, check useEffect dependencies

---

Hook called conditionally

Pattern: Error: Rendered more hooks than during the previous render

Root Cause: Hooks called inside conditions, loops, or nested functions

Common In: Conditional logic before hooks

Fix:

// ❌ Don't call hooks conditionally
function Component({ isLoggedIn }) {
  if (isLoggedIn) {
    const [user, setUser] = useState(null);  // Wrong!
  }
  return <div>Content</div>;
}

// ✅ Always call hooks at top level
function Component({ isLoggedIn }) {
  const [user, setUser] = useState(null);

  if (isLoggedIn) {
    // Use state here
  }

  return <div>Content</div>;
}

Prevention: Always call hooks at component top level, never inside conditions

---

Cannot update component while rendering

Pattern: Warning: Cannot update a component while rendering a different component

Root Cause: State update during render phase

Common In: Passing setState to child components incorrectly

Fix:

// ❌ Don't update parent state during render
function Child({ setParentState }) {
  setParentState(value);  // Wrong!
  return <div>Child</div>;
}

// ✅ Use useEffect for side effects
function Child({ setParentState, value }) {
  useEffect(() => {
    setParentState(value);
  }, [value, setParentState]);
  return <div>Child</div>;
}

Prevention: Use useEffect for side effects, don't call setState during render

---

Additional Patterns

See main SKILL.md for integration patterns and debugging workflow.

For real-world examples, see examples.md.