bug-fixing-assistant

name	Bug Fixing Assistant
description	Systematic debugging workflow for CircleTel - analyzes errors, identifies root causes, proposes fixes, and validates solutions with tests. Integrates with error-registry for known issues.
version	1.1.0
dependencies	python>=3.8, typescript>=5.0, error-registry

Bug Fixing Assistant Skill

A comprehensive skill for systematically debugging and fixing software bugs in the CircleTel codebase. Uses structured workflows to identify root causes, propose targeted fixes, and validate solutions.

RSI Integration: This skill connects to the error-registry for faster resolution of known issues.

When This Skill Activates

This skill automatically activates when you:

• Encounter runtime errors or exceptions
• Debug failing tests or build errors
• Investigate performance issues or memory leaks
• Troubleshoot API failures or timeout issues
• Fix infinite loading states or UI bugs
• Resolve database query problems
• Debug authentication or RLS policy issues
• Investigate TypeScript type errors

Keywords: bug, error, debug, fix, issue, broken, failing, crash, exception, timeout, undefined, null, 500 error, 403 error

Core Debugging Strategy

Phase 0: Check Error Registry (1-2 minutes) - NEW!

Before investigating, check if this is a known error.

Step 0.1: Match Error Signature

Check the error message against the registry:

Error Registry Location: .claude/skills/error-registry/

Commands:
- /errors top        # Show top 10 recurring errors
- /error ERR-001     # Get specific error details
- /errors search "RLS"  # Search by keyword

Step 0.2: Quick Lookup Table

Error Contains	Likely Match	Quick Fix
"loading stays true"	ERR-001	Add finally { setLoading(false) }
"row-level security"	ERR-002	Add service_role policy
"Promise<{ id:"	ERR-003	await context.params
"heap out of memory"	ERR-005	Use npm run build:memory
"401 Unauthorized"	ERR-006	Check BOTH header AND cookies

Step 0.3: If Match Found

1. Read the error pattern file for full solution
2. Apply the documented fix
3. Log occurrence (update lastSeen, increment count)
4. Skip to Phase 5 (Validation)

Step 0.4: If No Match Found

1. Continue to Phase 1 (Understand the Problem)
2. After fixing, add to registry using /errors add

┌─────────────────────────────────────────────────────────┐
│  BUG DETECTED                                           │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│  PHASE 0: Check Error Registry                          │
│  Match error signature against known patterns           │
└────────────────┬────────────────────────────────────────┘
                 │
     ┌───────────┴───────────┐
     │ KNOWN?                │
     ▼                       ▼
┌──────────────┐     ┌──────────────────────────┐
│ YES: Apply   │     │ NO: Continue to Phase 1  │
│ known fix    │     │ Investigate & fix        │
│ Skip to P5   │     │ Add to registry when done│
└──────────────┘     └──────────────────────────┘

---

Phase 1: Understand the Problem (5-10 minutes)

Don't jump to solutions. Invest time understanding the failure mode first.

Step 1.1: Gather Evidence

Collect all relevant information:

• Error messages: Full stack traces, console logs, error codes
• Reproduction steps: Exact sequence to trigger the bug
• Environment: Browser, Node version, deployment environment
• User impact: How many users affected? Critical or minor?
• Recent changes: What was deployed recently?

Step 1.2: Identify Failure Modes

Ask Claude to outline possible scenarios:

"What could cause [symptom] in [context]?"

Examples:
- "What could cause pagination to silently drop results in Next.js 15?"
- "Why might a Supabase RLS policy block authenticated requests?"
- "What scenarios cause React components to re-render infinitely?"

Step 1.3: Form Hypotheses

Generate testable hypotheses ranked by likelihood:

"Given this error: [error message]
And this context: [relevant code/logs]
What are the top 3 most likely root causes, ranked by probability?"

Phase 2: Investigate (15-30 minutes)

Step 2.1: Reproduce Locally

Always reproduce first before attempting fixes:

# CircleTel development setup
npm run dev:memory

# Check console for errors
# Navigate to affected page/feature
# Follow exact reproduction steps

Document the exact steps:

1. Navigate to [page]
2. Click [button]
3. Observe [unexpected behavior]

Step 2.2: Add Instrumentation

Add strategic logging to narrow down the issue:

console.log('[DEBUG] Function entry:', { params })
console.log('[DEBUG] Before API call:', { payload })
console.log('[DEBUG] API response:', { data, error })
console.log('[DEBUG] State update:', { oldState, newState })

Use DEBUG prefix to easily filter logs.

Step 2.3: Isolate the Problem

Use binary search to narrow scope:

• Comment out half the code
• Does bug still occur?
• If yes, bug is in remaining half
• If no, bug is in commented half
• Repeat until isolated

Phase 3: Analyze Root Cause (10-20 minutes)

Step 3.1: Review Related Code

Ask Claude to analyze the relevant code:

"Review this code for potential issues:

[paste code]

Context: [describe the bug]

Look for:
- Race conditions
- Missing error handling
- Incorrect state updates
- Type mismatches
- Missing null checks

Step 3.2: Check Architecture Patterns

For complex bugs, analyze architectural issues:

"Analyze this for architectural problems:

[paste relevant code sections]

Consider:
- Concurrency issues (Promise.all, async/await)
- State management problems (stale closures, derived state)
- Lifecycle issues (useEffect dependencies)
- Memory leaks (event listeners, timers)

Step 3.3: Identify CircleTel-Specific Patterns

Common CircleTel bug patterns:

1. Infinite Loading States

• Cause: Missing finally block in async callbacks
• Fix: Always set loading=false in finally block
• Example: components/providers/CustomerAuthProvider.tsx:64-76

2. RLS Policy Blocking API Access

• Cause: Missing service role policy
• Fix: Add service_role policy to table
• Example: See Database Migration Skill

3. Next.js 15 Params Type Error

• Cause: Async params not awaited
• Fix: const { id } = await context.params
• Example: See CLAUDE.md TypeScript Patterns

4. Memory Heap Overflow

• Cause: Large TypeScript compilation
• Fix: Use npm run build:memory
• Example: See package.json scripts

Phase 4: Propose Fix (5-15 minutes)

Step 4.1: Generate Targeted Solution

Ask Claude for fix proposals:

"Given this root cause: [analysis]

Propose a minimal fix that:
1. Resolves the issue
2. Matches CircleTel coding style
3. Doesn't introduce new bugs
4. Includes error handling

Show the exact code changes needed.

Step 4.2: Review for Side Effects

Check if fix affects other areas:

"This fix changes [component/function]:

[paste proposed fix]

What other parts of the codebase might be affected?
Search for:
- Files that import this
- Components that use this hook
- API routes that depend on this

Step 4.3: Apply Fix Locally

Make the change in your local environment:

// Example: Fix infinite loading state
useEffect(() => {
  const callback = async () => {
    try {
      const data = await fetchData()
      setState(data)
    } catch (error) {
      console.error('Failed:', error)
      setState(null)
    } finally {
      setLoading(false) // ✅ Always executes
    }
  }
  onAuthStateChange(callback)
}, [])

Phase 5: Validate (10-20 minutes)

Step 5.1: Test the Fix

Validation Checklist:

• Bug no longer reproduces
• Original functionality still works
• No new errors in console
• Type check passes: npm run type-check
• Build succeeds: npm run build:memory
• Related features still work

Step 5.2: Write Tests

Ask Claude to generate tests:

"Generate a test that verifies this fix:

Bug: [description]
Fix: [code change]
Expected behavior: [what should happen now]

Use [testing framework] and follow CircleTel patterns.

Step 5.3: Run Full Test Suite

# Type check
npm run type-check

# Build test
npm run build:memory

# E2E tests (if applicable)
npm run test:e2e

# Manual testing checklist
# - Test happy path
# - Test error scenarios
# - Test edge cases

Bug Type Templates

Template 1: Runtime Error

Symptom: Application crashes with error message

Investigation Prompt:

"Analyze this runtime error:

Error: [error message]
Stack trace: [stack trace]
File: [file:line]

1. What is the immediate cause?
2. What conditions trigger this?
3. Is this a timing issue, null reference, or logic error?
4. What's the safest fix?

Template 2: Infinite Loop/Loading

Symptom: UI stuck in loading state or infinite re-renders

Investigation Prompt:

"Debug this infinite loop/loading issue:

Component: [component name]
Code: [paste useEffect or relevant code]

Analyze for:
1. Missing dependency array
2. State updates triggering re-renders
3. Missing finally block
4. Async callback error handling

Template 3: API/Database Error

Symptom: API calls fail or return unexpected data

Investigation Prompt:

"Troubleshoot this API/database issue:

API: [endpoint]
Error: [error message or behavior]
Request: [request payload]
Response: [response or error]

Check for:
1. RLS policy blocking access
2. Missing authentication
3. Incorrect query parameters
4. Type mismatches in payload

Template 4: Type Error

Symptom: TypeScript compilation fails

Investigation Prompt:

"Fix this TypeScript error:

Error: [type error message]
File: [file:line]
Code: [relevant code]

1. What type is expected vs provided?
2. Is this a Next.js 15 async params issue?
3. Is this a missing type definition?
4. What's the minimal fix?

Template 5: Performance Issue

Symptom: Slow page load, high memory usage, or lag

Investigation Prompt:

"Analyze this performance issue:

Symptom: [slow loading, memory leak, etc.]
Context: [page, component, or operation]
Metrics: [load time, memory usage]

Investigate:
1. Unnecessary re-renders
2. Large data sets without pagination
3. Missing memoization
4. Inefficient database queries
5. Missing indexes

CircleTel-Specific Debugging Patterns

Pattern 1: Customer Dashboard Infinite Loading

Common Locations:

• app/dashboard/page.tsx
• components/providers/CustomerAuthProvider.tsx
• app/dashboard/*/page.tsx

Root Cause: Missing finally block in async auth callback

Fix Pattern:

useEffect(() => {
  const callback = async () => {
    try {
      // Fetch data
    } catch (error) {
      // Handle error
    } finally {
      setLoading(false) // ✅ CRITICAL
    }
  }
  onAuthStateChange(callback)
}, [])

Reference: components/providers/CustomerAuthProvider.tsx:64-76

Pattern 2: RLS Policy Blocking API Routes

Common Error: new row violates row-level security policy

Root Cause: Missing service role policy on table

Fix Pattern:

CREATE POLICY "service_role_all" ON public.table_name
  FOR ALL
  USING (auth.jwt() ->> 'role' = 'service_role');

Debug Steps:

1. Check RLS policies: SELECT * FROM pg_policies WHERE tablename = 'table_name'
2. Verify API uses service role client
3. Add service role policy if missing

Pattern 3: Next.js 15 Async Params Error

Common Error: Type 'Promise<{ id: string }>' is not assignable to type '{ id: string }'

Root Cause: Next.js 15 made params async

Fix Pattern:

// ❌ OLD (breaks in Next.js 15)
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const { id } = params
}

// ✅ NEW (Next.js 15 compatible)
export async function GET(
  request: NextRequest,
  context: { params: Promise<{ id: string }> }
) {
  const { id } = await context.params
}

Pattern 4: Supabase Client Type Mismatch

Common Error: Cannot read properties of undefined (reading 'from')

Root Cause: Wrong Supabase client for context

Fix Pattern:

// ✅ Server-side (API routes)
import { createClient } from '@/lib/supabase/server'
const supabase = await createClient() // Service role

// ✅ Client-side (components)
import { createClient } from '@/lib/supabase/client'
const supabase = createClient() // Anonymous with RLS

Pattern 5: Memory Heap Overflow

Common Error: JavaScript heap out of memory

Root Cause: Large TypeScript compilation or build

Fix Pattern:

# Use memory-optimized commands
npm run dev:memory          # 8GB heap
npm run type-check:memory   # 4GB heap
npm run build:memory        # 8GB heap

Debugging Workflows by Category

Workflow A: Frontend UI Bug

1. Reproduce in browser

   • Open DevTools console
   • Check for errors
   • Note exact steps

2. Check React DevTools

   • Inspect component props
   • Check state values
   • Look for re-render count

3. Add console.log strategically

   console.log('[DEBUG] Component render:', { props, state })
   console.log('[DEBUG] Before setState:', oldValue)
   console.log('[DEBUG] After setState:', newValue)
   

4. Isolate the component

   • Test component in isolation
   • Remove parent props temporarily
   • Check if issue persists

5. Review useEffect dependencies

   useEffect(() => {
     // Check this runs when expected
     console.log('[DEBUG] useEffect triggered')
   }, [/* Verify dependencies */])
   

Workflow B: API Route Error

1. Check API logs

   # Check Vercel logs
   # Or run locally with debug
   npm run dev:memory
   

2. Test with curl/Postman

   curl -X POST https://localhost:3000/api/endpoint \
     -H "Content-Type: application/json" \
     -d '{"test": "data"}'
   

3. Verify authentication

   • Check headers for auth token
   • Verify token is valid
   • Check RLS policies

4. Check database query

   const { data, error } = await supabase
     .from('table')
     .select()
   
   console.log('[DEBUG] Query result:', { data, error })
   

5. Review error response

   • Check status code
   • Read error message
   • Verify response format

Workflow C: Database/RLS Issue

1. Check RLS policies

   SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
   FROM pg_policies
   WHERE schemaname = 'public'
   AND tablename = 'your_table'
   ORDER BY policyname;
   

2. Test query directly

   -- In Supabase SQL Editor
   SELECT * FROM public.your_table LIMIT 10;
   

3. Verify service role policy exists

   SELECT * FROM pg_policies
   WHERE policyname LIKE '%service_role%'
   AND tablename = 'your_table';
   

4. Check foreign key constraints

   SELECT constraint_name, table_name, column_name
   FROM information_schema.key_column_usage
   WHERE table_name = 'your_table';
   

5. Review indexes

   SELECT indexname, indexdef
   FROM pg_indexes
   WHERE tablename = 'your_table';
   

Workflow D: Build/Type Error

1. Run type check

   npm run type-check:memory
   

2. Read error message carefully

   • Note file and line number
   • Understand expected vs actual type
   • Check for Next.js 15 patterns

3. Check import statements

   • Verify imports are correct
   • Check for missing type definitions
   • Ensure @ alias is used

4. Review recent changes

   git diff HEAD~1
   

5. Fix incrementally

   • Fix one error at a time
   • Re-run type check after each fix
   • Verify fix doesn't create new errors

Validation Checklist

After applying a fix, verify:

Immediate Checks (2 minutes)

• Bug no longer reproduces locally
• No new console errors
• No new console warnings
• Original feature still works

Code Quality (5 minutes)

• Type check passes: npm run type-check
• No linting errors: npm run lint
• Code follows CircleTel patterns
• Error handling is comprehensive

Build & Deploy (10 minutes)

• Build succeeds: npm run build:memory
• Test on staging environment
• No performance regression
• Database migrations work (if applicable)

Testing (15 minutes)

• Unit tests pass (if applicable)
• E2E tests pass: npm run test:e2e
• Manual testing of related features
• Edge cases tested

Documentation (5 minutes)

• Fix documented in commit message
• Updated CLAUDE.md if pattern is common
• Added to debugging knowledge base
• Team notified if critical

Quick Reference Commands

# Development with debugging
npm run dev:memory          # Start with 8GB heap
npm run type-check:memory   # Type check with memory

# Check logs
tail -f .next/server-logs.txt

# Database debugging
npx supabase db dump --schema public
npx supabase db execute -f debug.sql

# Test specific route
curl http://localhost:3000/api/endpoint

# Check build
npm run build:memory

# Clean rebuild
npm run clean && npm run build:memory

Common Bug Patterns & Solutions

Bug Pattern	Symptom	Root Cause	Quick Fix
Infinite Loading	UI stuck on "Loading..."	Missing finally block	Add finally { setLoading(false) }
403 API Error	RLS blocks request	Missing service role policy	Add service_role policy to table
Type Error	TypeScript won't compile	Next.js 15 async params	await context.params
Heap Overflow	Build fails with OOM	Large compilation	Use npm run build:memory
Undefined Error	Cannot read property of undefined	Missing null check	Add ?. optional chaining
Stale Data	Component shows old data	Missing dependency	Add to useEffect deps array

Resources

• Templates: See templates/ for debugging prompt templates
• Examples: See examples/ for real CircleTel bug fixes
• Checklists: See checklists/ for debugging workflows
• CLAUDE.md: CircleTel-specific debugging patterns

Best Practices

1. Reproduce first, fix second - Never fix what you can't reproduce
2. Add logging strategically - Use [DEBUG] prefix for easy filtering
3. Test incrementally - Verify each change doesn't break other features
4. Document patterns - Add common bugs to this skill
5. Use type safety - Let TypeScript catch bugs early
6. Follow CircleTel patterns - Check CLAUDE.md for established solutions

---

Version: 1.0.0 Last Updated: 2025-11-08 Maintained By: CircleTel Development Team Based On: Claude blog post "Fix Software Bugs Faster with Claude"