error-detective

Error Detective - Systematic Debugging and Error Resolution

Overview

Error Detective is a comprehensive debugging SKILL that applies a systematic methodology to efficiently identify, analyze, and resolve errors. It guides the debugging process from initial error discovery to verified resolution using the TRACE framework and structured analysis techniques.

Core Capabilities

Stack Trace Analysis

• Parsing and interpreting stack traces across multiple languages
• Distinguishing root causes from symptom errors
• Extracting relevant file paths and line numbers
• Understanding call chains and error propagation

Error Pattern Recognition

• Classifying errors by type (syntax, runtime, logic, integration)
• Identifying common error patterns and anti-patterns
• Recognizing framework-specific errors
• Mapping errors to possible root causes

Root Cause Analysis

• Distinguishing symptoms from underlying issues
• Tracing back along the error chain to the original point of occurrence
• Distinguishing environment issues from code issues
• Detecting configuration and dependency problems

Debugging Workflow Management

• Structured investigation process
• Hypothesis generation and testing
• Iterative refinement of understanding
• Documenting investigation results and solutions

TRACE Framework

TRACE is a systematic 5-step approach that can debug any error:

T - Trace the Error

Goal: Capture complete error information and context

1. Collect the full error message

   • The entire stack trace (not just the first few lines)
   • Error type and message
   • Timestamp and occurrence frequency
   • The environment in which the error occurred

2. Identify the error location

   • Exact file and line number
   • The function or method where the error occurred
   • Code context (surrounding lines)
   • The call stack from the entry point to the error point

3. Capture reproduction steps

   • Minimal steps for reproduction
   • Input data or parameters used
   • Expected result vs. actual behavior
   • Consistency of reproduction (always occurs, occurs intermittently, occurs rarely)

R - Read the Error Message

Goal: Extract all information from the error itself

1. Parse error components

   • Error type/class (TypeError, ValueError, etc.)
   • Error message content
   • Recommended fixes (if provided)
   • Related errors or warnings

2. Understanding error semantics

   • What that error type means in the given language/framework
   • What conditions cause this error
   • What the error message specifically says
   • Error code or status code

3. Identifying the error category

   • Syntax error (code cannot be parsed)
   • Runtime error (crash occurs during execution)
   • Logic error (result is wrong, no crash)
   • Integration error (external system failure)
   • Performance error (timeout, resource exhaustion)

A - Analyze the Context

Goal: Understand the broader context around the error

1. Code analysis

   • Review the failing line and surrounding code
   • Check recent changes to that code
   • Review function/method signatures and usage
   • Review related code that calls or is called by the failing code

2. Data analysis

   • Investigate the input values at the time of failure
   • Check data types and structures
   • Verify that the data meets the expected format/constraints
   • Identify edge cases or unexpected values

3. Environment analysis

   • Check dependencies and versions
   • Review configuration files
   • Validate environment variables
   • Check availability of required resources (files, network, memory)

4. State analysis

   • Application state at the time the error occurred
   • Previous operations that led to this state
   • Related shared state or global variables
   • Database or external system state

C - Check for Root Cause

Goal: Identify the underlying issue, not just the symptom

1. Tracing the error chain

   • Start from the bottom of the stack trace (the first error)
   • Trace upward to find the original cause
   • Distinguish between the point where the error occurred and the error handler
   • Identify wrapped or re-thrown errors

2. Testing hypotheses

   • Create specific, testable hypotheses
   • Isolate variables (change one at a time)
   • Verify assumptions using logging/debugging tools
   • Document confirmed or rejected hypotheses

3. Common root causes

   • Null/undefined 값: Missing initialization or validation
   • Type mismatches: Passing or returning the wrong data type
   • Off-by-one errors: Array/loop boundary issues
   • Race conditions: Failure by timing
   • Resource exhaustion: Insufficient memory, disk, or connections
   • Configuration errors: Incorrect or missing configuration
   • Dependency issues: Version conflicts or missing libraries
   • Permission errors: Insufficient access permissions
   • Network errors: Connectivity, timeout, or DNS issues
   • Data corruption: Invalid or unexpected data format

E - Execute the Fix

Goal: Implement and verify the solution

1. Designing the fix

   • Address the root cause, not the symptom
   • Consider side effects and edge cases
   • Plan for backward compatibility if needed
   • Choose the most maintainable solution

2. Careful implementation

   • Make minimal, targeted changes
   • Add validation and error handling
   • Include logging for future debugging
   • Document the fix and its rationale

3. Thorough verification

   • Confirm the original error is resolved
   • Test through the reproduction steps
   • Test edge cases and related functionality
   • Confirm no new errors were introduced

4. Documentation and prevention

   • Document the cause of the error
   • Document the solution and why it works
   • Add tests to prevent regression
   • Update documentation or add warnings if needed

Debugging workflow

Initial assessment (5 minutes)

1. 전체 에러 메시지 읽기
2. 에러 유형 및 심각도 식별
3. 에러 재현 가능 여부 확인
4. 영향도 평가 (차단형, 성능 저하, 단순 외관상 문제)
5. 조사 우선순위 결정

In-depth investigation (15-30 minutes)

1. TRACE 프레임워크를 체계적으로 적용
2. 디버깅 도구 사용 (scripts/debug_helper.py 참조)
3. 가설 생성 및 테스트
4. 진행하면서 발견 사항 문서화
5. 근본 원인으로 좁히기

Implementing the solution (varies by situation)

1. 근본 원인을 해결하는 수정 설계
2. 적절한 에러 핸들링과 함께 구현
3. 로깅 및 검증 추가
4. 철저한 테스트
5. 해결책 문서화

Verification and prevention (10 minutes)

1. 원래의 재현 단계로 수정 사항 검증
2. 관련 기능 테스트
3. 회귀 테스트 추가
4. 문서 업데이트
5. 배포 및 모니터링

Common error patterns by language

Python

AttributeError: 'NoneType' has no attribute 'X'

• Root cause: expected an object but the variable is None
• Check items: initialization, function return values, API responses
• Solution: add a null check, ensure proper initialization

KeyError: 'key_name'

• Root cause: the dictionary does not contain the expected key
• Check items: data source, parsing logic, key spelling
• Solution: use .get() with a default value, validate the data structure

ImportError / ModuleNotFoundError

• Root cause: the module is not installed or not on the path
• Check items: requirements.txt, virtual environment, PYTHONPATH
• Solution: install the missing package, fix the import path

IndentationError

• Root cause: inconsistent whitespace (tabs vs spaces)
• Check items: editor settings, copied code
• Solution: standardize on spaces (PEP 8), use a linter

JavaScript/TypeScript

TypeError: Cannot read property 'X' of undefined

• Root cause: accessing a property of an undefined object
• Check items: object initialization, async timing, API responses
• Solution: Optional chaining (?. operator), null check

ReferenceError: X is not defined

• Root cause: Using a variable before declaration or out of scope
• Check items: Variable declaration, scope, hoisting issues
• Solution: Variable declaration, fix scope, verify imports

Promise rejection / Uncaught (in promise)

• Root cause: Asynchronous task failed without a catch handler
• Check items: API calls, file operations, async/await usage
• Solution: Add .catch() or use try/catch with await

SyntaxError: Unexpected token

• Root cause: Invalid syntax mainly occurring during JSON or code parsing
• Check items: JSON structure, matching brackets, semicolons
• Solution: Validate JSON, fix syntax, check for copy/paste errors

Java

NullPointerException

• Root cause: Calling a method on a null object reference
• Check items: Object initialization, method return values
• Solution: Add null checks, use Optional, ensure initialization

ClassNotFoundException

• Root cause: Class cannot be found in the classpath
• Check items: Dependencies, build configuration, package structure
• Solution: Add dependencies, fix classpath, verify package/class names

ConcurrentModificationException

• Root cause: Collection was modified during iteration
• Check items: Nested loops, multithreading, iterator usage
• Solution: iterator.remove(), use CopyOnWriteArrayList, or synchronization

Error severity classification

Critical (fix immediately)

• Application crash or unable to start
• Data loss or corruption
• Security vulnerability
• Production outages
• Payment or transaction failure

High (fix promptly)

• Major feature failure
• Performance degradation affecting users
• Error affecting multiple users
• Complex workarounds

Medium (schedule a fix)

• Secondary feature failure
• Cosmetic issue with impact
• Error with an easy workaround
• Edge case failure

Low (backlog)

• Cosmetic issue
• Minor improvements
• Rare edge case
• Non-critical warning

Debugging tools and techniques

Logging best practices

import logging

# 구조화된 로깅 설정
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# 컨텍스트와 함께 로깅
logger = logging.getLogger(__name__)
logger.debug(f"Processing item: {item_id}, user: {user_id}")
logger.error(f"Failed to process: {error}", exc_info=True)

Strategic breakpoints

1. Point where the error occurs: Capture the exact state at the time the error occurs
2. Before the error occurs: Verify input values and preconditions
3. After the error occurs: Observe the error propagation process
4. Decision points: Verify logic branching points
5. Inside the loop: Check iteration variables

Strategic print debugging

# 컨텍스트 정보를 포함한 디버그 출력 추가
print(f"DEBUG: function_name called with {param1=}, {param2=}")
print(f"DEBUG: variable state before operation: {var=}")
print(f"DEBUG: condition check: {condition=}, result: {result=}")

Binary Search Debugging

When the error location is unclear:

1. Add a checkpoint in the middle of the code path
2. Determine whether the error is before or after the checkpoint
3. Repeat for the remaining half
4. Converge quickly on the error location

Rubber Duck Debugging

Explain the code line by line to someone (or something):

1. Makes you examine your assumptions
2. You often find the error while explaining
3. Clarifies complex logic
4. Identifies gaps in knowledge

Using the Debug Helper script

scripts/debug_helper.py The utility provides automated assistance features:

# 파일에서 스택 트레이스 파싱
python scripts/debug_helper.py parse-trace error.log

# 에러 패턴 추출
python scripts/debug_helper.py analyze-log application.log

# 디버그 세션 시작 (로그 생성)
python scripts/debug_helper.py session start "Login error investigation"

# 세션에 노트 추가
python scripts/debug_helper.py session note "Tested with different users - same error"

# 해결책과 함께 세션 종료
python scripts/debug_helper.py session close "Fixed: Added null check for user.profile"

Best Practices

Do's

• Read the entire error message: Don't skip the details.
• Consistent reproduction: Secure a reliable way to reproduce before debugging.
• Change only one thing at a time: Isolate what fixed the problem.
• Document as you go: Record hypotheses, tests, and findings.
• Use version control: Commit before debugging so you can revert if needed.
• Add tests: Prevent regressions after the fix.
• Fix the root cause: Don't just patch the symptoms.
• Share knowledge: Document the solution for the team.

Don'ts

• Don't guess: Validate assumptions with data.
• Don't skip reading the error: Error messages contain important information.
• Don't change multiple things at once: You won't know what fixed it.
• Don't impulsively delete code: Comment it out first and understand why it was there.
• Don't ignore warnings: Today's warning becomes tomorrow's error.
• Don't fix without understanding: You may break something else.
• Don't forget tests: Verify that the fix works and doesn't create new issues.

Common debugging scenarios

Scenario 1: "It worked yesterday"

Approach:

1. Check recent changes (git diff, git log)
2. Review dependency updates
3. Check environment changes
4. Look for time-dependent logic
5. Compare settings across environments

Common causes:

• Recent code changes
• Updated dependencies
• Configuration changes
• Database schema changes
• External API changes
• Certificate expiration

Scenario 2: "It works on my machine"

Approach:

1. Environment comparison (OS, dependencies, settings)
2. Check environment variables
3. Verify file paths and permissions
4. Compare data between environments
5. Explore hardcoded assumptions

Common causes:

• Different dependency versions
• Missing environment variables
• Different file paths
• Database state differences
• Operating system differences
• Missing configuration files

Scenario 3: "Intermittent failures"

Approach:

1. Identify failure patterns (timing, frequency, conditions)
2. Explore race conditions
3. Check resource availability
4. Review concurrent operations
5. Add extensive logging
6. Increase the number of reproduction attempts

Common causes:

• Race conditions
• Memory leaks
• Unstable external services
• Network issues
• Timing-dependent logic
• Resource exhaustion

Scenario 4: "Errors occur only in production"

Approach:

1. Check production-only settings
2. Review the characteristics of production data
3. Check production load/scale
4. Review production dependencies
5. Review security/permission settings

Common causes:

• Edge cases in production data
• Scale/load-related issues
• Production-only settings
• Different security policies
• Firewall or network restrictions
• Features integrated only for production

Advanced techniques

Bisect Debugging (Git)

Finding which commit introduced the bug:

git bisect start
git bisect bad                 # 현재 버전에 버그가 있음
git bisect good v1.2.0        # v1.2.0 버전은 정상이였음
# Git이 중간 커밋을 체크아웃함
# 테스트 후 good/bad 마킹
git bisect good/bad
# Git이 범인 커밋을 식별할 때까지 반복
git bisect reset

Heisenbug (observer effect)

Errors that disappear when you start debugging:

Strategy:

• Add logging without breakpoints
• Use an environment similar to production for debugging
• Review timing and concurrency issues
• Check initialization/timing dependencies
• Use non-intrusive monitoring

Memory Profiling

Checking memory leaks and performance:

# Python 메모리 프로파일링
import tracemalloc

tracemalloc.start()
# ... 코드 실행 ...
snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')

for stat in top_stats[:10]:
    print(stat)

Network Debugging

Checking API and integration errors:

Tools:

• Browser DevTools Network tab
• curl with verbose flag (-v)
• Postman for API testing
• Wireshark for packet inspection
• Network proxies (Charles, Fiddler)

Check items:

• Request/response headers
• Status codes
• Request/response body
• Timing (latency, timeouts)
• SSL/TLS issues

Quick Reference

TRACE Framework Quick Checklist

☐ T - TRACE
  ☐ 전체 에러 메시지 캡처 완료
  ☐ 스택 트레이스 수집 완료
  ☐ 재현 단계 문서화 완료
  ☐ 환경 식별 완료

☐ R - READ
  ☐ 에러 유형 식별 완료
  ☐ 에러 메시지 분석 완료
  ☐ 에러 카테고리 결정 완료
  ☐ 관련 에러 확인 완료

☐ A - ANALYZE
  ☐ 코드 검토 완료
  ☐ 데이터 조사 완료
  ☐ 환경 검증 완료
  ☐ 상태 조사 완료

☐ C - CHECK
  ☐ 에러 체인 추적 완료
  ☐ 가설 테스트 완료
  ☐ 근본 원인 식별 완료
  ☐ 가정 검증 완료

☐ E - EXECUTE
  ☐ 수정 설계 완료
  ☐ 수정 구현 완료
  ☐ 수정 검증 완료
  ☐ 방지 대책 추가 완료

Error Priority Matrix

영향도 →      Low        Medium       High        Critical
빈도 ↓
High         Medium     High         Critical    Critical
Medium       Low        Medium       High        Critical
Low          Low        Low          Medium      High
Rare         Backlog    Low          Medium      High

Additional Resources

Examples

• examples/debugging_workflow.md - Step-by-step debugging process examples
• examples/common_errors.md - Catalog of frequently occurring error patterns and solutions
• examples/stack_traces.txt - Stack trace examples provided with analysis

Scripts

• scripts/debug_helper.py - Python debugging utilities for trace parsing and session management

Further Learning

• Language-specific debugging documentation
• Framework error handling guides
• Profiling and performance analysis tools
• Testing and quality assurance practices

---

Remember: Debugging is a detective investigation. Be systematic and patient, and let the evidence lead you to the truth. Every error message is a clue waiting for your understanding.