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.

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 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

finally { setLoading(false) }

await context.params

npm run build:memory

?.

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"