debugging（调试）

Resources

scripts/
  validate-debugging.sh
references/
  debugging-patterns.md

Debugging Quality Skill

This skill teaches you how to debug systematically using GoodVibes precision tools. Effective debugging requires a methodical approach: reproduce the issue, isolate the cause, identify the root problem, apply a fix, and verify the solution.

When to Use This Skill

Load this skill when:

• Investigating runtime errors or exceptions
• Tracing unexpected behavior or logic errors
• Analyzing network request/response issues
• Debugging state management problems
• Diagnosing performance bottlenecks
• Investigating build or compilation errors
• Understanding TypeScript type errors
• Performing root cause analysis

Trigger phrases: "debug this error", "why is this failing", "investigate the issue", "trace the problem", "analyze the error".

Core Workflow

Phase 1: Reproduce - Confirm the Issue

Before debugging, confirm you can reproduce the issue reliably.

Step 1.1: Gather Error Context

Collect all available error information.

precision_exec:
  commands:
    - cmd: "npm run typecheck 2>&1"
    - cmd: "npm run lint 2>&1"
    - cmd: "npm run build 2>&1"
  verbosity: standard

What to capture:

• Complete error message and stack trace
• Error type and code (if applicable)
• File path and line number
• Timestamps and environment info
• User actions that triggered the error

Step 1.2: Find Error Occurrences

Search for similar errors in the codebase.

discover:
  queries:
    - id: error_throw_sites
      type: grep
      pattern: "throw new (Error|TypeError|RangeError)"
      glob: "**/*.{ts,tsx,js,jsx}"
    - id: error_handlers
      type: grep
      pattern: "catch\\s*\\("
      glob: "**/*.{ts,tsx,js,jsx}"
    - id: console_errors
      type: grep
      pattern: "console\\.(error|warn)"
      glob: "**/*.{ts,tsx,js,jsx}"
  verbosity: locations

Pattern categories:

Step 1.3: Reproduce Locally

Run the failing operation to confirm reproduction.

precision_exec:
  commands:
    - cmd: "npm run dev"
      timeout_ms: 5000
  verbosity: minimal

Reproduction checklist:

• Error reproduces consistently
• Minimal steps to reproduce identified
• Environment matches production (Node version, deps)
• Error message matches reported issue

Phase 2: Isolate - Narrow Down the Cause

Reduce the problem space to find where the error originates.

Step 2.1: Read the Stack Trace

Analyze the call stack to understand execution flow.

Stack trace example:

TypeError: Cannot read property 'name' of undefined
    at getUserName (src/utils/user.ts:42:18)
    at UserProfile (src/components/UserProfile.tsx:15:22)
    at renderWithHooks (node_modules/react/cjs/react.development.js:1234)

Reading strategy:

1. Start at the top - The actual error location
2. Trace backwards - Follow the call chain
3. Ignore node_modules - Focus on your code
4. Find the entry point - Where did the bad data come from?

precision_read:
  files:
    - path: "src/utils/user.ts"
      extract: content
      range: {start: 35, end: 50}
    - path: "src/components/UserProfile.tsx"
      extract: content
      range: {start: 10, end: 25}
  verbosity: standard

Step 2.2: Trace Data Flow

Follow the data from source to error point.

discover:
  queries:
    - id: function_calls
      type: grep
      pattern: "getUserName\\("
      glob: "**/*.{ts,tsx}"
    - id: data_sources
      type: grep
      pattern: "(fetch|axios|prisma).*user"
      glob: "**/*.{ts,tsx}"
    - id: prop_passing
      type: grep
      pattern: "user=\\{"
      glob: "**/*.tsx"
  verbosity: locations

Data flow analysis:

• Where does the data originate? (API, database, props)
• What transformations occur? (map, filter, destructure)
• What assumptions are made? (not null, specific shape)
• Where could it become undefined?

Step 2.3: Check Boundary Conditions

Test edge cases where errors commonly occur.

discover:
  queries:
    - id: array_access
      type: grep
      pattern: "\\[[0-9]+\\]|\\[.*\\]"
      glob: "**/*.{ts,tsx}"
    - id: null_checks
      type: grep
      pattern: "(if.*===.*null|if.*===.*undefined|\\?\\.|\\?\\?)"
      glob: "**/*.{ts,tsx}"
    - id: optional_chaining
      type: grep
      pattern: "\\?\\."
      glob: "**/*.{ts,tsx}"
  verbosity: locations

Common boundary issues:

Phase 3: Identify - Pinpoint the Root Cause

Determine the underlying problem, not just the symptom.

Step 3.1: Analyze Error Patterns

Classify the error to understand common causes.

Type Errors

precision_exec:
  commands:
    - cmd: "npm run typecheck 2>&1 | head -50"
  verbosity: standard

Common TypeScript errors:

Runtime Errors

discover:
  queries:
    - id: unsafe_access
      type: grep
      pattern: "\\.[a-zA-Z]+(?!\\?)"
      glob: "**/*.{ts,tsx}"
    - id: async_errors
      type: grep
      pattern: "await.*(?!try)"
      glob: "**/*.{ts,tsx}"
  verbosity: files_only

Common runtime errors:

• Cannot read property X of undefined
• Cannot read property X of null
• X is not a function
• X is not iterable
• Maximum call stack size exceeded (infinite recursion)

Step 3.2: Check Dependencies and Imports

Module resolution errors are common.

discover:
  queries:
    - id: imports
      type: grep
      pattern: "^import.*from"
      glob: "**/*.{ts,tsx}"
    - id: dynamic_imports
      type: grep
      pattern: "import\\("
      glob: "**/*.{ts,tsx}"
    - id: require_statements
      type: grep
      pattern: "require\\("
      glob: "**/*.{ts,js}"
  verbosity: locations

Common import issues:

Step 3.3: Validate Assumptions

Question assumptions about data shape and state.

precision_grep:
  queries:
    - id: type_assertions
      pattern: "as (unknown|any|[A-Z][a-zA-Z]+)"
      glob: "**/*.{ts,tsx}"
  output:
    format: context
    context_before: 2
    context_after: 2
  verbosity: standard

Dangerous assumptions:

• API always returns expected shape
• Array is never empty
• User is always authenticated
• Data is always valid
• Props are always provided

Validate with:

• Runtime type validation (Zod, Yup)
• Type guards (if (typeof x === 'string'))
• Null checks (if (x!= null))
• Default values (x?? defaultValue)

Phase 4: Fix - Apply the Solution

Implement the fix based on root cause analysis.

Step 4.1: Choose the Right Fix

Match the fix to the problem type.

Type Safety Fixes

// Before: Implicit any
function getUser(id) {
  return users.find(u => u.id === id);
}

// After: Explicit types
function getUser(id: string): User | undefined {
  return users.find(u => u.id === id);
}

Null Safety Fixes

// Before: Unsafe access
const name = user.profile.name;

// After: Optional chaining
const name = user?.profile?.name ?? 'Anonymous';

Async Error Handling

// Before: Unhandled promise
await fetchData();

// After: Try/catch
try {
  await fetchData();
} catch (error: unknown) {
  logger.error('Failed to fetch data', { error });
  throw new AppError('Data fetch failed', { cause: error });
}

Array Boundary Fixes

// Before: Unsafe access
const first = items[0];

// After: Safe access
const first = items.length > 0 ? items[0] : null;
// Or: const first = items.at(0) ?? null;

Step 4.2: Add Defensive Code

Prevent similar errors in the future.

Input validation:

import { z } from 'zod';

const userSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

function processUser(data: unknown) {
  const user = userSchema.parse(data); // Throws if invalid
  // Now user is type-safe
}

Type guards:

function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'email' in value
  );
}

if (isUser(data)) {
  // TypeScript knows data is User
  logger.info('User email', { email: data.email });
}

Error boundaries (React):

import { ErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error }: { error: Error }) {
  return (
    <div role="alert">
      <p>Something went wrong:</p>
      <pre>{error.message}</pre>
    </div>
  );
}

<ErrorBoundary FallbackComponent={ErrorFallback}>
  <MyComponent />
</ErrorBoundary>

Step 4.3: Apply the Fix

Use precision_edit to make the change.

precision_edit:
  edits:
    - path: "src/utils/user.ts"
      find: |
        function getUserName(user) {
          return user.name;
        }
      replace: |
        function getUserName(user: User | undefined): string {
          return user?.name ?? 'Unknown';
        }
  verbosity: minimal

Phase 5: Verify - Confirm the Fix Works

Validate that the fix resolves the issue without breaking anything.

Step 5.1: Type Check

Ensure TypeScript errors are resolved.

precision_exec:
  commands:
    - cmd: "npm run typecheck"
  verbosity: standard

All type errors must be resolved.

Step 5.2: Run Tests

Confirm tests pass.

precision_exec:
  commands:
    - cmd: "npm test"
  verbosity: standard

If tests fail:

• Fix introduced a regression
• Test expectations need updating
• Test revealed another issue

Step 5.3: Manual Verification

Reproduce the original error scenario.

precision_exec:
  commands:
    - cmd: "npm run dev"
      timeout_ms: 5000
  verbosity: minimal

Verification checklist:

• Original error no longer occurs
• Edge cases handled (null, empty, large values)
• No new errors introduced
• Performance not degraded
• User experience improved

Phase 6: Network Debugging

Debug API requests and responses.

Step 6.1: Find Network Calls

Locate all HTTP requests.

discover:
  queries:
    - id: fetch_calls
      type: grep
      pattern: "fetch\\("
      glob: "**/*.{ts,tsx,js,jsx}"
    - id: axios_calls
      type: grep
      pattern: "axios\\.(get|post|put|delete|patch)"
      glob: "**/*.{ts,tsx,js,jsx}"
    - id: api_routes
      type: glob
      patterns: ["src/app/api/**/*.ts", "pages/api/**/*.ts"]
  verbosity: locations

Step 6.2: Check Request/Response Handling

Validate error handling for network calls.

precision_grep:
  queries:
    - id: fetch_with_catch
      pattern: "fetch\\([^)]+\\).*catch"
      glob: "**/*.{ts,tsx,js,jsx}"
  output:
    format: context
    context_after: 5
  verbosity: standard

Common network issues:

Debugging CORS:

// Next.js API route
export async function GET(request: Request) {
  return Response.json(data, {
    headers: {
      'Access-Control-Allow-Origin': '*', // Development only - use specific origin in production
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

Debugging authentication:

// Check for auth header
const token = request.headers.get('Authorization')?.replace('Bearer ', '');
if (!token) {
  return Response.json({ error: 'Unauthorized' }, { status: 401 });
}

try {
  const session = await verifyToken(token);
} catch (error: unknown) {
  logger.error('Token verification failed', { error });
  return Response.json({ error: 'Invalid token' }, { status: 401 });
}

Step 6.3: Validate Request Payloads

Ensure request data is correct.

discover:
  queries:
    - id: request_bodies
      type: grep
      pattern: "(body:|JSON.stringify)"
      glob: "**/*.{ts,tsx}"
    - id: validation_schemas
      type: grep
      pattern: "z\\.object\\("
      glob: "**/*.{ts,tsx}"
  verbosity: locations

Request validation:

import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

export async function POST(request: Request) {
  const body = await request.json();
  const result = createUserSchema.safeParse(body);

  if (!result.success) {
    return Response.json(
      { error: 'Validation failed', details: result.error.flatten() },
      { status: 400 }
    );
  }

  // Now result.data is type-safe
}

Phase 7: State Debugging

Debug React state and state management.

Step 7.1: Find State Usage

Locate state declarations and updates.

discover:
  queries:
    - id: useState_calls
      type: grep
      pattern: "useState<?"
      glob: "**/*.{tsx,jsx}"
    - id: state_updates
      type: grep
      pattern: "set[A-Z][a-zA-Z]*\\("
      glob: "**/*.{tsx,jsx}"
    - id: useEffect_hooks
      type: grep
      pattern: "useEffect\\("
      glob: "**/*.{tsx,jsx}"
  verbosity: locations

Common state issues:

Stale closure fix:

// Before: Stale closure
const [count, setCount] = useState(0);

function increment() {
  setTimeout(() => {
    setCount(count + 1); // count is stale
  }, 1000);
}

// After: Functional update
function increment() {
  setTimeout(() => {
    setCount(prev => prev + 1); // Always current
  }, 1000);
}

useEffect dependency fix:

// Before: Missing dependency
useEffect(() => {
  fetchData(userId);
}, []); // userId changes ignored

// After: Complete dependencies
useEffect(() => {
  fetchData(userId);
}, [userId]); // Re-runs when userId changes

Step 7.2: Check for State Mutations

Find direct state mutations (anti-pattern).

discover:
  queries:
    - id: array_mutations
      type: grep
      pattern: "\\.(push|pop|shift|unshift|splice)\\("
      glob: "**/*.{tsx,jsx}"
    - id: object_mutations
      type: grep
      pattern: "[a-zA-Z]+\\.[a-zA-Z]+\\s*=\\s*"
      glob: "**/*.{tsx,jsx}"
  verbosity: locations

Immutable updates:

// Before: Mutation
const [items, setItems] = useState([1, 2, 3]);
items.push(4); // BAD: Mutates state
setItems(items);

// After: Immutable
setItems([...items, 4]); // GOOD: New array

// Object updates
const [user, setUser] = useState({ name: 'Alice', age: 30 });
setUser({ ...user, age: 31 }); // GOOD: New object

Phase 8: Performance Debugging

Diagnose performance bottlenecks.

Step 8.1: Find Performance Anti-patterns

Search for common performance issues.

discover:
  queries:
    - id: n_plus_one
      type: grep
      pattern: "(for|forEach|map).*await.*(prisma|db|query)"
      glob: "**/*.{ts,tsx}"
    - id: inline_objects
      type: grep
      pattern: "(onClick|onChange|style)=\\{\\{"
      glob: "**/*.{tsx,jsx}"
    - id: missing_memo
      type: grep
      pattern: "(map|filter|reduce|sort)\\("
      glob: "**/*.{tsx,jsx}"
  verbosity: locations

Performance issues:

Step 8.2: Profile Build Performance

Check for slow builds.

precision_exec:
  commands:
    - cmd: "npm run build"
  verbosity: standard

Build performance issues:

• Large bundle size (check with bundle analyzer)
• Slow TypeScript compilation (check tsconfig)
• Missing tree-shaking (check imports)
• Development dependencies in production (check package.json)

Phase 9: Root Cause Analysis

Go beyond symptoms to find underlying issues.

Step 9.1: Ask Why Five Times

Drill down to the root cause.

Example:

1. Why did the app crash? - User data was undefined
2. Why was user data undefined? - API returned null
3. Why did API return null? - Database query returned no rows
4. Why were there no rows? - User ID was incorrect
5. Why was user ID incorrect? - Route parameter parsing failed

Root cause: Route parameter parsing doesn't handle edge cases.

Step 9.2: Check System Dependencies

Validate environment and dependencies.

precision_exec:
  commands:
    - cmd: "node --version"
    - cmd: "npm --version"
    - cmd: "npm list --depth=0"
  verbosity: minimal

Common dependency issues:

• Version mismatch (package.json vs lockfile)
• Peer dependency conflicts
• Outdated packages with known bugs
• Missing native dependencies

Step 9.3: Review Recent Changes

Find what changed before the error appeared.

precision_exec:
  commands:
    - cmd: "git log --oneline -10"
    - cmd: "git diff HEAD~5..HEAD"
  verbosity: standard

Git bisect for complex issues:

git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Test, then mark:
git bisect good  # or bad
# Repeat until culprit commit found

Phase 10: Prevention - Avoid Future Issues

Add safeguards to prevent recurrence.

Step 10.1: Add Tests

Write tests that catch the error.

import { describe, it, expect } from 'vitest';

describe('getUserName', () => {
  it('should handle undefined user', () => {
    expect(getUserName(undefined)).toBe('Unknown');
  });

  it('should handle user without name', () => {
    expect(getUserName({ id: '123' })).toBe('Unknown');
  });

  it('should return user name', () => {
    expect(getUserName({ id: '123', name: 'Alice' })).toBe('Alice');
  });
});

Step 10.2: Add Logging

Log key decision points for future debugging.

import { logger } from '@/lib/logger';

function processUser(user: User | undefined) {
  if (!user) {
    logger.warn('User is undefined in processUser');
    return null;
  }

  logger.info('Processing user', { userId: user.id });

  try {
    // Process user
  } catch (error: unknown) {
    logger.error('Failed to process user', { userId: user.id, error });
    throw error;
  }
}

Logging best practices:

• Use structured logging (JSON)
• Include context (user ID, request ID)
• Use appropriate log levels (error, warn, info, debug)
• Never log sensitive data (passwords, tokens)
• Use correlation IDs to trace requests

Step 10.3: Add Monitoring

Track errors in production.

Error tracking (Sentry, Rollbar):

import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
  beforeSend(event, hint) {
    // Filter sensitive data
    if (event.request) {
      delete event.request.cookies;
    }
    return event;
  },
});

Custom error classes:

export class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
    public context?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'AppError';
  }
}

throw new AppError('User not found', 'USER_NOT_FOUND', 404, { userId });

Common Debugging Patterns

See references/debugging-patterns.md for detailed patterns organized by category.

Error Pattern Detection

Use discover to find multiple error patterns at once.

discover:
  queries:
    # Type safety issues
    - { id: any_usage, type: grep, pattern: ':\\s*any', glob: '**/*.{ts,tsx}' }
    - { id: type_assertions, type: grep, pattern: 'as (any|unknown)', glob: '**/*.{ts,tsx}' }
    # Runtime safety
    - { id: unsafe_access, type: grep, pattern: '\\.[a-zA-Z]+(?!\\?)', glob: '**/*.{ts,tsx}' }
    - { id: unhandled_promises, type: grep, pattern: 'await.*(?!try)', glob: '**/*.{ts,tsx}' }
    # Performance
    - { id: n_plus_one, type: grep, pattern: 'for.*await.*prisma', glob: '**/*.{ts,tsx}' }
    - { id: inline_objects, type: grep, pattern: 'onClick=\\{\\{', glob: '**/*.{tsx,jsx}' }
  verbosity: locations

Systematic Error Analysis

Step 1: Categorize the error

• Type error (compile-time)
• Runtime error (null, undefined, type mismatch)
• Logic error (wrong behavior, no exception)
• Performance error (too slow)
• Network error (API failure)

Step 2: Find similar patterns

• Search for the error message
• Search for the error type
• Search for the failing function name

Step 3: Trace the data

• Where does the data come from?
• What transformations occur?
• Where does it fail?

Step 4: Validate assumptions

• Is the data shape correct?
• Are types accurate?
• Are edge cases handled?

Step 5: Fix and verify

• Apply the fix
• Run type check
• Run tests
• Verify manually

Precision Tools for Debugging

Discover Tool

Run parallel searches to find error patterns.

discover:
  queries:
    - id: error_sites
      type: grep
      pattern: "throw new"
      glob: '**/*.{ts,tsx,js,jsx}'
    - id: catch_blocks
      type: grep
      pattern: "catch\\s*\\("
      glob: '**/*.{ts,tsx,js,jsx}'
    - id: console_logs
      type: grep
      pattern: "console\\.(log|error|warn)"
      glob: '**/*.{ts,tsx,js,jsx}'
  verbosity: locations

Precision Grep

Search with context for understanding surrounding code.

precision_grep:
  queries:
    - id: error_context
      pattern: "TypeError|ReferenceError|RangeError"
      glob: "**/*.{ts,tsx,js,jsx}"
  output:
    format: context
    context_before: 5
    context_after: 5
  verbosity: standard

Precision Exec

Run diagnostic commands.

precision_exec:
  commands:
    - cmd: "npm run typecheck 2>&1"
    - cmd: "npm run lint 2>&1"
    - cmd: "npm test 2>&1"
  verbosity: standard

Precision Edit

Apply fixes atomically.

precision_edit:
  edits:
    - path: "src/utils/user.ts"
      find: "user.name"
      replace: "user?.name ?? 'Unknown'"
  verbosity: minimal

Validation Script

Use scripts/validate-debugging.sh to validate debugging practices.

./scripts/validate-debugging.sh /path/to/project

The script checks:

• console.log statements removed from production
• Error boundaries implemented
• Source maps configured
• Proper logging libraries used
• Try/catch blocks handling errors
• Debug dependencies excluded from production

Quick Reference

Debugging Checklist

Reproduce:

• Error reproduces consistently
• Minimal reproduction steps identified
• Environment matches
• Error message captured

Isolate:

• Stack trace analyzed
• Data flow traced
• Boundary conditions tested
• Similar patterns found

Identify:

• Error categorized
• Root cause identified (not symptom)
• Assumptions validated
• Dependencies checked

Fix:

• Appropriate fix chosen
• Defensive code added
• Fix applied
• No new issues introduced

Verify:

• Type check passes
• Tests pass
• Manual verification complete
• Edge cases tested

Prevent:

• Tests added for the issue
• Logging added
• Monitoring configured
• Documentation updated

Error Severity Guide

Critical (fix immediately):

• Application crashes
• Data loss or corruption
• Security vulnerabilities
• Production outage

High (fix soon):

• Feature completely broken
• Poor user experience
• Performance degradation
• Type safety violations

Medium (fix when able):

• Edge case failures
• Minor UX issues
• Console warnings
• Missing error handling

Low (fix eventually):

• Code style issues
• Missing documentation
• Optimization opportunities
• Refactoring needs

Common Mistakes to Avoid

Fixing symptoms, not causes:

• BAD: Add null check without understanding why it's null
• GOOD: Trace why the value is null and fix the source

Skipping verification:

• BAD: Apply fix and assume it works
• GOOD: Run tests, type check, and manual verification

Ignoring edge cases:

• BAD: Fix the common case only
• GOOD: Test null, undefined, empty, and large values

No prevention:

• BAD: Fix the bug and move on
• GOOD: Add tests and logging to prevent recurrence

Advanced Techniques

Binary Search Debugging

For complex issues, use binary search to narrow down.

Comment out half the code:

1. Comment out half the function
2. If error persists, problem is in remaining half
3. If error disappears, problem is in commented half
4. Repeat until isolated

Rubber Duck Debugging

Explain the problem out loud:

1. Describe what the code should do
2. Describe what it actually does
3. Walk through line by line
4. Often reveals the issue during explanation

Time-Travel Debugging

Use git to find when the bug was introduced:

git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Test each commit
git bisect good  # or bad

Logging Strategy

Trace important values:

function processData(data: unknown) {
  logger.debug('Input data', { data });

  const validated = schema.parse(data);
  logger.debug('Validated data', { validated });

  const transformed = transform(validated);
  logger.debug('Transformed data', { transformed });

  return transformed;
}

Use correlation IDs:

import { v4 as uuid } from 'uuid';

export async function POST(request: Request) {
  const requestId = uuid();
  logger.info('Request started', { requestId });

  try {
    const result = await processRequest(request);
    logger.info('Request completed', { requestId });
    return Response.json(result);
  } catch (error: unknown) {
    logger.error('Request failed', { requestId, error });
    throw error;
  }
}

Integration with Other Skills

• Use error-recovery for automated fix attempts
• Use code-review to catch errors during review
• Use testing-strategy to prevent regressions
• Use performance-audit for performance issues
• Use security-audit for security vulnerabilities

Resources

• references/debugging-patterns.md - Common error patterns by category
• scripts/validate-debugging.sh - Automated debugging practice validation
• Chrome DevTools - https://developer.chrome.com/docs/devtools/
• React DevTools - https://react.dev/learn/react-developer-tools
• Node.js Debugging Guide - https://nodejs.org/en/docs/guides/debugging-getting-started/